Chapter 4. Create an OAS specification

This section will help you to create an OpenAPI Specification (OAS) compliant specification for your REST API, which is required to power ActiveDocs on your Developer Portal. If you only want to read the code, all the examples are on OAS Petstore example source code.

4.1. About OpenAPI Specification (OAS)

3scale ActiveDocs are based on the specification of RESTful web services called Swagger (from Wordnik). This example is based on the Extended OpenAPI Specification Petstore example and draws all the specification data from the OpenAPI Specification 2.0 specification document.

OAS is not only a specification. It also provides a full feature framework around it:

  1. Servers for the specification of the resources in multiple languages (NodeJS, Scala, and others).
  2. A set of HTML/CSS/Javascripts assets that take the specification file and generate the attractive UI.
  3. A OAS codegen project, which allows generation of client libraries automatically from a Swagger-compliant server. Support to create client-side libraries in a number of modern languages.

4.2. 3scale ActiveDocs and OAS

ActiveDocs is an instance of OAS. With ActiveDocs, you do not have to run your own OAS server or deal with the user interface components of the interactive documentation. The interactive documentation is served and rendered from your 3scale Developer Portal.

3scale 2.8 introduces with a limited support OAS 3.0 in ActiveDocs. This means that some features working with ActiveDocs, such as autocompletion, are not yet fully integrated, and consequently 3scale defaults to OAS 2.0 when creating new accounts. For more details about OAS 3.0 and ActiveDocs, refer to Section 2.1, “Using OAS 3.0 with 3scale”.

Prerequisites

  • Ensure that the template used in the Developer Portal implements the same OAS version specified in the Admin Portal.

Procedure

  1. Build a specification of your API compliant with OAS.
  2. Add the specification to your Admin Portal.

With these steps the interactive documentation will be available. Your developers will be able to launch requests against your API through your Developer Portal.

If you already have a OAS-compliant specification of your API, you can add it in your Developer Portal (see the tutorial on the ActiveDocs configuration).

3scale extended the OAS specification in several ways to accommodate certain features that were needed for our own interactive API documentation:

  • Auto-fill of API keys
  • OAS proxy to allow calls to non-CORS enabled APIs

4.3. Creating the specification of your API

We recommend that you first read the specification from the original source. See the OAS Specification.

On the OAS site there are multiple examples of specifications. If you like to learn by example, you can follow the example of the Petstore API by the OAS API Team.

4.3.1. Learning by example: the Petstore API

The Petstore API is an extremely simple API. It is meant as a learning tool, not for production.

The Petstore API is composed of 4 methods:

  • GET /api/pets - returns all pets from the system
  • POST /api/pets - creates a new pet in the store
  • GET /api/pets/{id} - returns a pet based on a single ID
  • DELETE /api/pets/{id} - deletes a single pet based on the ID

The Petstore API is integrated with 3scale, and for this reason you must add an additional parameter for authentication. For example, with the User Key authentication method, the parameter is sent in the header. For information about other authentication methods, see Authentication patterns.

You need to add the parameters:

user_key: {user_key}

The user_key will be sent by the developers in their requests to your API. The developers will obtain those keys on your Developer Portal. On receiving the key, you must to perform the authorization check against 3scale using the Service Management API.

For your developers, the documentation of your API represented in cURL calls would look like this:

curl -X GET "http://example.com/api/pets?tags=TAGS&limit=LIMIT" -H "user_key: {user_key}"
curl -X POST "http://example.com/api/pets" -H "user_key: {user_key}" -d "{ "name": "NAME", "tag": "TAG", "id": ID }"
curl -X GET "http://example.com/api/pets/{id}" -H "user_key: {user_key}"
curl -X DELETE "http://example.com/api/pets/{id}" -H "user_key: {user_key}"

However, if you want the documentation to look like the OAS Petstore Documentation, you must create a Swagger-compliant specification like the associated Petstore swagger.json file. You can use this specification out-of-the-box to test your ActiveDocs. But remember that this is not your API. You can learn more in the next section.

4.3.2. More on the OAS specification

The OAS specification relies on a resource declaration that maps to a hash encoded in JSON. Take the Petstore swagger.json file as an example and go step by step.

4.3.2.1. OAS object

This is the root document object for the API specification. It lists all the highest level fields.

Warning

The host must be a domain and not an IP address. 3scale will proxy the requests made against your Developer Portal to your host and render the results. This requires your host and basePath endpoint to be whitelisted by us for security reasons. You can only declare a host that is your own. 3scale reserves the right to terminate your account if we detect that you are proxying a domain that does not belong to you. This means that local host or any other wildcard domain will not work.

4.3.2.2. Info object

The Info object provides the metadata about the API. This will be presented in the ActiveDocs page.

4.3.2.3. Paths object

The paths object holds the relative paths to the individual endpoints. The path is appended to the basePath to construct the full URL. The paths may be empty, due to ACL constraints.

Parameters that are not objects use primitive data types. In Swagger, these are based on the types supported by the JSON-Schema Draft 4. There is an additional primitive data type "file" but it will work only if the API endpoint has CORS enabled (so the upload won’t go through api-docs gateway). Otherwise, it will get stuck on the gateway level.

Supported datatypes

Currently OAS supports the following dataTypes:

  • integer with possible formats: int32 and int64. Both formats are signed.
  • number with possible formats: float and double
  • plain string
  • string with possible formats: byte, date, date-time, password and binary
  • boolean

4.3.3. OAS design and editing tools

The following tools are useful for designing and editing your OpenAPI specification:

  • The open source Apicurio Studio enables you to design and edit your OpenAPI-based APIs in a web-based application. Apicurio Studio provides a design view so you do not need detailed knowledge of the OpenAPI specification. The source view enables expert users to edit directly in YAML or JSON. For more details, see Getting Started with Apicurio Studio.

    Red Hat also provides a lightweight version of Apicurio Studio named API Designer, which is included with Fuse Online on OpenShift. For more details, see Developing and Deploying API Provider Integrations.

  • The JSON Editor Online is useful if you are very familiar with the JSON notation. It gives a pretty format to compact JSON and provides a JSON object browser.
  • The Swagger Editor enables you to create and edit your OAS API specification written in YAML in your browser and preview it in real time. You can also generate a valid JSON specification, which you can upload later in your 3scale Admin Portal. You can use the live demo version with limited functionality or deploy your own OAS Editor.

4.3.4. ActiveDocs auto-fill of API keys

Auto-fill of API keys is a useful extension to the OAS specification in 3scale ActiveDocs. In the parameters, you can define the x-data-threescale-name field with the following values depending on your API authentication mode:

  • user_keys: Returns the user keys for applications of the services that use API key authentication only.
  • app_ids: Returns the IDs for applications of the services that use App ID/App Key (OAuth and OpenID Connect are also supported for backwards compatibility).
  • app_keys: Returns the keys for applications of services that use App ID/App Key (OAuth and OpenID Connect are also supported for backwards compatibility).

API key authentication example

The following example shows using "x-data-threescale-name": "user_keys" for API key authentication only:

"parameters": [
  {
    "name": "user_key",
    "description": "Your access API Key",
    "type": "string",
    "in": "query",
    "x-data-threescale-name": "user_keys",
    "required": true
  },
]

App ID/App Key authentication example

For App ID/App Key authentication mode, specify "x-data-threescale-name": "app_ids" for the parameter that represents the application ID, and "x-data-threescale-name": "app_keys" for the parameter that represents the application key.

When you have declared your parameters, ActiveDocs will automatically prompt the ActiveDocs user to log in to the Developer Portal to get their keys as shown in the following screenshot:

Auto-fill when not logged-in

If the user is already logged in, ActiveDocs will show the latest five keys that could be relevant for them so that they can test right away without having to copy and paste their keys.

Auto-fill when logged-in
Note

The x-data-threescale-name field is an extension to the OAS specification that will be ignored outside the domain of ActiveDocs.