Tutorial: Designing A Basic REST API

Describing The API

Where flowcharts and swim lanes document the inner workings of an API, its external appearance and interaction with other applications is documented by API specifications.

Flowcharts do not generally describe the actual interfaces and parameters of an API and were that the case they would be incredibly difficult to read and fathom.  Therefore the API specifications is generally referred to by developers or those wishing to interact with the API at a programmatic level.

We have already discussed standards around API documentation.  In this tutorial we will continue to follow these standards and produce a set of live documentation for our mock API.

The live documentation of our mock API can be seen at YourAPIExpert’s Swagger Viewer and below I will describe some essential items in the documentation.

Headers And Introductions
swagger: '2.0'
schemes:
  - http
  - https
host: localhost
basePath: /
info:
  contact:
    email: yourapiexpert@gmail.com
    name: YourAPIExpert.com
    url: 'http://www.yourapiexpert.com'
  description: 'YourAPIExpert provides information, tutorials and reviews on all things API and integration.'
  title: YourAPIExpert
  version: '1'
  x-logo:
    backgroundColor: '#FFFFFF'
    url: 'http://www.yourapiexpert.com/wp-content/uploads/2017/01/The-Developer-Series-Header.jpg'
  x-unofficialSpec: true
externalDocs:
  description: YourAPIExpert.com Tutorial
  url: 'http://www.yourapiexpert.com/2017/02/01/tutorial-designing-basic-rest-api/'
consumes:
  - application/json
produces:
  - application/json
securityDefinitions: {}

Starting at lines 3-4 we describe the two transport methods this API is available in. In production environments it is recommended to only offer secure HTTPS access and remote HTTP completely.  However as our API is still basic at this point we will continue to offer it in HTTP.

Lines 8-11 describe the contact information of the author, division or organization responsible for the API and the documentation.  In most cases this will provide information to the developer community working with your API but on internal documentation it might refer to the group or division responsible for the development of APIs.  Rarely does it name any one particular individual.

Lines 22-25 notifies the developer that the mock API expects to receive JSON input and will render all output in the same JSON format.

Endpoints

Below is the specifications for the POST endpoint.  As it is the more complex endpoint to document whilst still being familiar to the GET method we will focus a little more intently on it.

paths:
  /hello/{name}:
    get:
      description: 'Greets the caller in a JSON-friendly way through path parameters.'
      operationId: Get_Hello
      tags:
        - greet
      parameters:
        - description: 'The name of the person to greet.'
          in: path
          name: name
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/result'
        '400':
          description: Error response
          schema:
            $ref: '#/definitions/error'
      security: []
      summary: Greets caller.
  /hello:
    post:
      description: 'Greets the caller in a JSON-friendly way through HTTP body data.'
      operationId: Post_Hello
      tags:
        - greet
      parameters:
        - description: 'The name of the person to greet.'
          in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/request'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/result'
        '400':
          description: Error response
          schema:
            $ref: '#/definitions/error'
      security: []
      summary: Greets caller.

Lines 28-29 show us that the API expects to receive a GET request in the format ‘/hello/{name}‘.  Here {name} refers to a special placeholder variable required by default.  In other words if the request was sent as GET ‘/hello’ it would be rejected.  If it were sent as GET ‘/hello/world’ the special purpose {name} variable would be replaced by the string ‘world’.

In the POST request of Lines 51-74 there is no special purpose variable in the path (line 51).  Instead this endpoint expects to receive the data in the body of the POST request.  As discussed in our earlier ‘Essentials Series’ the HTTP POST  method allows for unformatted  text to be transmitted in the body.  Even were the text formatted in to JSON there still needs to be a method to communicate the expected format to developers.

Swagger achieves this with the use of schemas and in lines 57-63 our specifications describe the body of the POST.  Note in line 63 we make note that the body contains a schema which is used by Swagger later in the rendering of the UI documentation.

Between lines 64-72 we document two types of responses.  The first is the response for a successful request and again in lines 67-68 we see that it is supported by a schema.  On lines 69-72 we document the expected error response which also conforms to a schema.

Schemas

Instead of bloating the documentation with schema information which makes it difficult to read in-line by humans, Swagger provides a convenient means by which to document the schema at the end of the document and make references to it.  This keeps the documentation clean and allows for reusability as error messages should be consistent throughout the API and its endpoints.

definitions:
  request:
    properties:
      hello:
        type: string
    type: object
  result:
    properties:
      response:
        type: string
    type: object
  error:
    type: object
    properties:
      code:
        type: integer
        format: int16
        description: HTTP error code.
      status:
        type: string
        description: HTTP status text.
      message:
        type: string
        description: HTTP error description.

Between lines 76-80 we see the schema definition for the earlier body request in the HTTP POST method.  It calls for an object to be supplied whose property is called ‘hello’.

Lines 86-98 describe the error response which is a JSON object containing a code (of type integer), status (string) and a descriptive error message (strong).  Note how the Swagger standard allows us to describe the parameters as well as their types.

As a complete documentation set these specifications can now be rendered by any compatible Swagger parser such as the one hosted by YourAPIExpert

Up Next: Creating the REST API

Pages: 1 2 3 4 5 6

Written by YourAPIExpert