API Definitions

Our REST API is defined with the swagger file, which contains the instructions for API Manager. Swagger is open-source API development and design tool which helps us design our APIs for the outside world.

To access our API Definitions, you can clone the api_manager repository.

git clone https://git.inter-iot.eu/Inter-IoT/api_manager
cd api_manager/Definitions/

Writing Swagger definition

Example

swagger: "2.0"
info:
  title: TITLE
  description: Description of the API
tags:
  - name: example
    description: This is example tag
consumes:
  - application/json
produces:
  - application/json

paths:
  /example/endpoint:
    get:
      tags:
        - example
      summary: Get request to example endpoint
      description: "Description"
      produces:
        - application/json
      parameters:
        - name: Parameter
          in: header
          required: false
          type: string
      responses:
        "200":
          description: Success.
          schema:
            type: array
            items:
              $ref: "#/definitions/ExampleDef"
        "401":
          description: Unauthorized.
definitions:
  TestObject:
    - $ref: "#/definitions/ExampleDef"
    - type: object
      properties:
        object-name:
          type: object
          sub-string: 
            type: string
          additionalProperties:
            type: string

In the head of the yaml file we can place all the information about the API, such as title, description, tags, contact info and much more.

  • The tags property is sum of all the tags we are using on our endpoints, so we can organize our APIs by tags.
  • The consumes and produces properties are used for defining what types of content does the API support and should accept or produce via HTTP Requests.

  • paths property contains all the paths to which API responds or accepts their requests. Each path must have defined its type of HTTP method and the parameters it consumes. It is also good practice to include a response for each method, so the user is aware if his response was processed correctly.

    Note: Each path can have multiple distinctive HTTP methods.

  • The response property defines what responses this endpoint returns and what are the generic response models for each endpoint.

  • definitions property is special. It is commonly used when we need to re-use some property multiple times, but we do not want to repeat ourselves. Then we create a definition, which we can reference anywhere in the .yaml file with the $ref tag.