OpenAPI 3.0 - New interesting features

Recently, the OAI (a consortium formed by companies such as MuleSoft, Software AG, IBM, Salesforce, etc) has released the version 3.0 of the OpenAPI specification, formerly known as Swagger.

In the next sections, some of the new features of the version 3.0 are described.

Support of multiple servers

On version 2.0 it was included the field host; it is a String field used to identify the host (name or IP) serving the API.

On the version 3.0, there is a new field named servers that supports an array of objects. These objects can also store a Map of variables that will be used for substitution in the server's URL template:

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      },
                 {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    }
    }
  ]
}

Support of multiple OAuth flows

On version 2.0, under the Security Definitions Objects, there is a field called flow (type String) with these valid values: "implicit", "password", "application" or "accessCode".

Now, on version 3.0 the field is called flows and as the name suggests, it supports an array of several OAuth flows. The name of the flows has changed too: now application is called clientCredentials, and accessCode has been renamed to authorizationCode.

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    },
    "authorizationCode": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "tokenUrl": "https://example.com/api/oauth/token",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

RequestBody introduced

In the version 3.0 it is possible now to specify under "components" a set of objects of type RequestBody:

{
  "description": "user to add to the system",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User Example", 
            "externalValue": "https://foo.bar/examples/user-example.json"
          } 
        }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
          "user" : {
            "summary": "User example in XML",
            "externalValue": "https://foo.bar/examples/user-example.xml"
          }
        }
    },
    "text/plain": {
      "examples": {
        "user" : {
            "summary": "User example in Plain text",
            "externalValue": "https://foo.bar/examples/user-example.txt" 
        }
      } 
    },
    "*/*": {
      "examples": {
        "user" : {
            "summary": "User example in other format",
            "externalValue": "https://foo.bar/examples/user-example.whatever"
        }
      }
    }
  }
}

Support of OpenID Connect

The Security Scheme Object has changed as well. On version 2.0 the valid types for the security scheme were: "basic", "apiKey" or "oauth2". Now, "basic" has been renamed to "http" and a new type has been introduced: "openIdConnect".

When using openIdConnect, this new field in the Security Scheme Object must be used: openIdConnectUrl. This field will store the OpenId Connect URL to discover OAuth2 configuration values. 

Parameter locations: Cookies

On version 2.0, there were five possible locations of parameters: "query", "header", "path", "formData" or "body". On version 3.0 "formData" and "body" have been removed, and a new type has been introduced: "cookie".

Callbacks

Now, when describing the API operation on a path, it is possible not only to define the parameters and the responses, but also the callbacks, as a map of out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation:

      callbacks:
        onData:
          # when data is sent, it will be sent to the `callbackUrl` provided
          # when making the subscription PLUS the suffix `/data`
          {$request.query.callbackUrl}/data:
            post:
              requestBody:
                description: subscription payload
                content:
                  application/json:
                    schema:
                      properties:
                        timestamp:
                          type: string
                          format: date-time
                        userData:
                          $ref: '#/components/schemas/UserLogData'
              responses:
                '202':
                  description: |
                    Your implementation should return this HTTP status code
                    if the data was received successfully
                '204':
                  description: |
                    Your server should return this code if no longer 
                    interested in further updates

HTTP Status Codes

In the new version, to define a range of response codes, it is possible to use the uppercase wildcard character X. For example, 2XX represents all response codes between [200-299]. The following range definitions are allowed: 1XX, 2XX, 3XX, 4XX, and 5XX.

* * * *

José Ramón Huerga is an IT Professional with more than 15 years of experience in IT, delivering projects in areas such as API Management, Banking, CRM, ECM and SOA. Currently is working in the UK implementing API Projects (CMA OpenBanking, PSD2) using IBM API Connect.