Using Swagger to describe an API

Microservices and Pace Layering

Micrososervices Architecture

There is a lot of hype around at present for API’s or Microservices. This is a good thing because they represent a new way of looking the SDLC by breaking down applications into smaller more manageable pieces. Martin Fowler sums it up well at http://martinfowler.com/articles/microservices.html by highlighting the differences between traditional monolithic applications and Microservices.

Microservices appear to be a concrete implementation of the abstract concept of pace layering put forward by Gartner to solve emerging platforms for IT delivery (http://www.gartner.com/newsroom/id/1923014). The monolithic applications may stay around as systems of record but new ways are needed to manage systems of differentiation and systems of innovation.  My current thinking around Microservices is they enable the exposure of corporate data in new innovative ways and also allow corporations to look at ways of exposing themselves into customer processes rather than driving customers into their processes.

Defining an API

Anyway the above would make a great blog post but tonight I am looking at how to define part of the business  requirements for using Microservices. In this case it is looking at how to define technical requirements or an API specification. An API specification is a descriptive document that defines the expected inputs and outputs for a Microservice which is exposed as a Web API call typically for invocation via a HTTP/REST request.

The goal of creating an API specification is to be descriptive and not proscriptive and to define an endpoint that someone can create a client for and call. I think it is important to be descriptive and to describe exactly what needs to be provided but also what is expected to come out of an API request.  What I like about doing this is that it allows me to concentrate solely on the customer experience at first and design the solution based on how the software will be used rather than what an end system requires.

The Example – Blog Post Routing

To give this a concrete example, what I would like as an active blogger to be able to use an API request to publish blog articles from my phone and also from Microsoft Word or Excel.  A requirement for this is to have a well defined endpoint that exposes enough fields and capabilities that I am able to create a post in an editor of choice, create images, and submit to an API for routing to the blogging platform of choice. In this case there are two blogs, one is this blog (philipmunce.wordpress.com) and the second is an internal company blog for my employer (www.mexia.com.au). I use my personal blog to record my current learning’s about technology and to elicit feedback on my thought bubbles. For work I need to capture project progress and decisions and also put up reference information.

Swagger

So that I can describe the API I need a language. In this case I am using Swagger (http://swagger.io/) but there are others such as WADL which is the REST equivalent of WSDL.  Swagger is promoted as a way of documenting ASP.NET Web APIs (http://bitoftech.net/2014/08/25/asp-net-web-api-documentation-using-swagger/) and also has the benefit of providing a free online editor (http://editor.swagger.io/?#/).  Swagger uses a language known as YAML which stands for yet another markup language and is similar to JSON in that it is designed to be machine and human readable.

Defining API for Business Processes

When defining the API I started by considering what the basic use case was. In this case it involves a person (i.e. myself) submitting a request to upload a blog post.  This will eventually be done by calling the WordPress API (http://wp-api.org/) and the Confluence equivalent. But I don’t want to have to necessarily remember how to submit to both all the time plus there is a marketplace being built for Azure Web API’s that should have an exposed API for making the physical blog posts.  What I would do then is to provide a common interface for any blogging platform allowing for a new post to be submitted. For me to effectively do this what I can do is change my thinking from being system centric to being business process centric. This simply means that I think in terms of business processes and business process objects.  A business process is something (set of tasks, decisions etc) that delivers value to a customer, a business process object is a document going through state changes as part of the process.  In this case the business process is blogging or knowledge sharing. The value is improved knowledge both for myself and readers and the process object is the blog post itself.

One thing that is interesting about business processes is that they have a lifecycle both for the process and the object. In the case of the blog post a rough lifecycle is conceptualization (or discovery), followed by scribing and analysis, followed by submission, followed by formatting, followed by pruning, followed by reviewing and moving back into conceptualization. Like a lot of lifecycle methodologies this roughly correlates to the Plan, Do, Check, Act cycle.  What this means for the API is that because the blog post could be thought of as ‘alive’ the planning for API calls needs to take the lifecycle into consideration and a rough sequence of events is given below along with the anticipated capabilities needed to support the lifecycle.

  • Conceptualization – diagramming, searching,
  • Scribing and analysis – clipping tools, screen captures, scrapbooks, saving pages
  • Submission – blog posting, multi platforms and devices, templates
  • Formatting – template to blog format, images and attachments
  • Pruning – easy updating, keyword analytics
  • Reviewing – comments, social promotion, comparisons to other knowledge
  • … (back to conceptualisation for next blog post)

Content Office API

For the v1.0 API endpoint the blog post can be assumed to be in a simple format containing content which is either paragraphs, lists (numbered and ordered) and headings.  More complicated content can be supported in subsequent versions of the API.  The process object in this case is a blog post, which I am abstracting up to the more generic term of ‘Article’ in line with the HTML5 specifications.  The hierarchy for an article is: Content -> Article which means that I want to use the term Content in the API definition and the term Article as the process object inside the API.  The API itself then is called the Content Office API to reflect that the API supports a business process very similar to building a set of articles as content for a newspaper in an office (actually I wanted Content Foundry but someone has already taken that name, http://contentfoundry.net/).

Using Swagger

swagger.io options

To get started using Swagger I went to the http://swagger.io/ web page and scrolled down to the ‘Swagger tools & Resources” section.  Under the ‘Swagger Editor’ section I then selected the Demo option.

swagger.io.petstore example

This brought up a great looking editor with an example YAML file for the Swagger Petstore as an example.

swagger.io.articles example

What I then did is replace references to pet with references to article and articles to build up an API request to POST a new article to the API for submission.

Comments

Leave a Reply

Your email address will not be published.