This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Contracts

Contracts

Unlike SOAP APIs, which is effectively considered the predecessor of REST APIs, there was no solution for built-in documentation and schema validation from the beginning. Therefore, there were a lot of proprietary approaches that sometimes worked better and sometimes worse.

OpenAPI

Swagger also emerged from such a solution-seeking approach, and is effectively a compilation of several open source ideas. The way of Swagger, especially the possibility to create client and server automatically based on a complete API documentation, helped to break through and finally ensured that today Swagger is developed as OpenAPI and is an official API standard since 2016.

The name Swagger has survived to this day, but only represents the tooling and no longer the API standard itself.

1 - OpenAPI Contracts

OpenAPI Contracts

The OpenAPI Specification is an API description format for REST APIs. It is the successor of Swagger Specification.
The specification contains:

  • Description
  • Authentication information
  • Endpoints (like /tasks) and operations (HTTP verbs like GET, POST..)
  • Optionally additional information like contact, licensing, terms of use and more

Versions

The current version is 3 and can be found on GitHub: OpenAPI-Specification version list

Formats

The OpenAPI Specification usually is written in YAML, but sometimes also the JSON-format is used. Both variants enable a format that can be read by both humans and machines.

Contract First development

In the wild, one often sees the approach that the server is implemented first and the contract is generated from it - for example with an OpenAPI middleware.
This often results in APIs that do not follow the REST standard and often delays the development of clients, since they have to constantly wait for the further development of the server. Likewise, breaking changes are a big problem with a server-implementation-first approach.
This is not recommended.

It is generally advisable to develop the contract first and then implement it.
This approach is considered the more stable variant in the development process and ensures long-term planning, so that the risks of breaking the API are reduced.

Sample

openapi: "3.0.0"
info:
  title: Task API
  description: This is a sample server for tasks
  termsOfService: https://dotnet.rest/terms/
  contact:
    name: API Support
    url: https://www.dotnet.rest/support
    email: [email protected]
  license:
    name: MIT
    url: dotnet.rest
  version: 1.0.1
servers:
  - url: https://api.dotnet.rest/v1
    description: Task API V1
  - url: https://api.dotnet.rest/latest
    description: Task API latest
  - url: https://dev-api.dotnet.rest/v2
    description: Task API v2 DEV
paths:
  /tasks:
    get:
      summary: "Gets all your tasks"
      operationId: "getAllTasks"
      responses:
        "200":
          description: "successful operation"
          content:
            application/json:
              schema: 
                type: "array"
                items: 
                  $ref: "#/components/schemas/TaskModel"
    post:
      summary: "Gets all your tasks"
      operationId: "addTasks"
      requestBody:
        description: "Task create model"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreateModel'
      responses:
        "200":
          description: "successful operation"
          content:
            application/json:
              schema: 
                type: "array"
                items: 
                  $ref: "#/components/schemas/TaskModel"
                  
  /tasks/{id}:
    get:
      summary: "Gets all your tasks"
      operationId: "getTask"
      parameters:
        - name: id
          description: Id of task
          in: path
          required: true
          schema:
            type: "integer"
            format: "int32"
      responses:
        "200":
          description: "task found and returned"
          content:
            application/json:
              schema:
                  $ref: "#/components/schemas/TaskModel"
        "404":
          description: "task not found by given Id"
                  
                  
components:
  schemas:
    TaskModel:
      type: "object"
      properties:
        id:
          type: "integer"
          format: "int32"
        title:
          type: "string"
        isDone:
          type: "boolean"
    TaskCreateModel:
      type: "object"
      properties:
        id:
          type: "integer"
          format: "int32"
        title:
          type: "string"
        isDone:
          type: "boolean"

OpenAPI Homepage

2 - Swagger Contracts

Swagger Contracts

Unlike SOAP APIs, which is effectively considered the predecessor of REST APIs, there was no solution for built-in documentation and schema validation from the beginning. Therefore, there were a lot of proprietary approaches that sometimes worked better and sometimes worse.

OpenAPI

Swagger also emerged from such a solution-seeking approach, and is effectively a compilation of several open source ideas. The way of Swagger, especially the possibility to create client and server automatically based on a complete API documentation, helped to break through and finally ensured that today Swagger is developed as OpenAPI and is an official API standard since 2016.

The name Swagger has survived to this day, but only represents the tooling and no longer the API standard itself.