Adding and Updating OpenAPI Documents

Overview

When building and refining an API hub, there is often additional data about the API that needs to be included with the API. This API hub-related data about the API (which we also call “metadata”) is beyond what is supported in the standard OpenAPI Specification (OAS). This data can vary from system to system or gateway to gateway.

Given this challenge, Rapid is providing a standardized way to map this data into your Hub, building on the OAS standards. As contributing members of the Open API Foundation, building solutions that conform to and extend OAS standards is part of our DNA and in line with industry standards. Adding this data to an OpenAPI document greatly simplifies the process of exposing data in an API hub.

📘

Must use the Platform API

To upload OAS documents with Rapid extensions, you must use the Platform API. For more information and sample code, see this page

📘

Validate your OAS documents

It is recommended that you use an OAS validation tool such as Swagger editor before uploading your OAS documents to Rapid.

📘

$ref objects

Currently only local $ref objects are supported when uploading OAS documents to Rapid. The local reference is de-referenced when importing the OAS document. Therefore if you then export the OAS file, you will not see the local references.

Rapid currently does not support remote and URL references.

📘

Single security policy

When importing an OAS file with a security policy, the entire security policy is applied at the API project level.

Mapping existing OAS metadata fields to the Rapid interface

There are fields that we consider to be metadata (hub-related data about the API) that already exist within the OpenAPI specification. For these cases, the field values from the OpenAPI document are imported and displayed in the Rapid user interface (UI).

In the table below, the fields are separated by dots, indicating the location of each field in the hierarchy of the OpenAPI document. For example, “info.title” can be read as “the title field of the info object”.

Example:

{
 "openapi": "3.0.0",
 "info": {
   "title": "Test XX",
   "description": "This is the short description",
   "version": "1.0.1",
   "termsOfService": "https://policies.google.com/terms?hl=en-US",
   
...

Two OAS extension field types

Rapid has two types of fields related to its OAS extensions. Both types of fields are prefixed with “x-”, indicating that the field is a vendor extension to the OpenAPI Specification. The first are fields relating to data that can generally be used in other systems, such as gateways, API repositories, or any external integration. The second are fields that are useful only in relation to RapidAPI.

Fields that may be generally relevant outside of Rapiduse the following naming convention:

“x-{{field}}”

Example:

"x-category": "Other",
"x-long-description": "This is the LONG description",
"x-website": "https://rapidapi.com",
"x-public": true,
 ...

Fields that are Rapid-specific use the following naming convention:

“x-{{rapidapi-field}}”

Example:

"x-rapidapi-info": {
   "apiId": "api_5ad6a620-6325-456c-b97f-6296331e439a",
   "apiVersionId": "apiversion_be84abe7-7f3a-4a85-9610-cb8ad0c6c806"
}

Note that field names inside extension objects (such as x-rapidapi-info.apiId) do not need to be prefixed with “x-”.

Rapid extension fields, arrays, and objects

The following fields and objects relate to Rapid OpenAPI Specification extensions: [#info-object-fields

• Info Object Fields
• Badges Array
• RapidAPI Info Object
• Gateways Array
• Documentation Object

Info object fields

These fields are added to the existing “info” object of an OpenAPI document. To indicate this hierarchy, a dot is placed after “info” in the field names below.

Example of info object fields:

"info": {
  "title": "Test XX",
  "description": "This is the short description",
  "version": "1.0.1",
  "x-category": "Other",
  "x-long-description": "This is the LONG description",
  "x-website": "https://rapidapi.com",
  "x-public": false,
  "x-thumbnail": "https://rapidapi-prod-apis.s3.amazonaws.com/72f81d15-39c4-46c4-a940-ae94fbb0b9c6.png",
  "x-version-lifecycle": "active",
  "x-collections" : ["Collection Name"],
  "termsOfService": "https://policies.google.com/terms?hl=en-US",
  ...

Badges Array (“info.x-badges”)

The x-badges array is added to the info object of an OpenAPI document. Badges (also known in Rapid as tags) are name-value pairs that can be added to the API to optimize its discoverability. For more information on RapidAPI badges/tags, see Tags .

Since there can be multiple badges for an API, the value of the x-badges field is an array containing one or more objects. Each object contains “name” and “value” fields. If the info.x-badges array is not defined in the OAS file, it will be set to the default empty array [].

If one or more tags have the Make Required for Providers checkbox selected in the Admin Panel, those tags/badges must be set in the OpenAPI document or a validation error is returned when trying to create an API.

If a specified badge name does not exist, an exception is created and the API will not be created.

If a badge value is added that doesn’t currently exist and the “Allow Providers to Add Values” flag for the API is set to true, the value is applied to the API. If “Allow Providers to Add Values” is set to false, an exception is created and the API will not be created.

Badges are set via the OpenAPI document only on API creation. Changes to the badges array are ignored for API updates via the OpenAPI document. Changes to the badges/tags can still be made in the Provider Dashboard, Admin Panel, or by using the Add API Tag endpoint of the Platform API.

Example of the x-badges object:

"x-badges": [
  {
    "name": "API Type",
    "value": "REST"
  },
  {
    "name": "Region",
    "value": "Global"
  }
]

RapidAPI Info Object (“x-rapidapi-info”)

The x-rapidapi-info object is automatically added at the root level of an OpenAPI document and is available in OAS documents that have been downloaded from Rapid. The apiID or apiVersionId may need to be specified when making certain Platform API calls.

Example of the x-rapidapi-info object:

"x-rapidapi-info": {
   "apiId": "api_5ad6a620-6325-456c-b97f-6296331e439a",
   "apiVersionId": "apiversion_be84abe7-7f3a-4a85-9610-cb8ad0c6c806"
},

Gateways Array (“x-gateways”)

The x-gateways array is added at the root level of an OpenAPI document. It contains an array of objects containing “url” fields for API gateways related to the API. Assuming you have more than one gateway configured for your Enterprise Hub, you can add multiple gateways as an array. API gateways in Rapid are usually specified so that API calls from clients are made directly to the API gateway, rather than via the Rapid Runtim. For more information, see API Gateways.

If the x-gateways array is not specified in the OpenAPI document, the default value of [{}] will be used.

If a url in the x-gateways array has not been added the the Enterprise Hub by an Environment Admin (see API Gateways, the import of the OpenAPI document will fail.

Example of the x-gateways array:

"x-gateways": [{ "url": "rapidapi.com" }, { "url": "example.com" }],

Documentation Object (“x-documentation”)

The x-documentation object is added at the root level of an OpenAPI document. You can use this object to highlight your API's features and provide detailed documentation. This information will show up on your API listing's About tab on the Rapid Hub.

If the documentation object is not defined in the OpenAPI document, it will be set to an empty object {}.

Spotlights Array (“x-documentation.spotlights”)

You can link existing content or resources for your API as a “Featured Spotlight” on your API listing's About tab. This helps developers understand and use your API. For more information regarding spotlights, see the documentation.

The spotlights array contains objects with the following three fields.

Tutorials Array (“x-documentation.tutorials”)

You can showcase how to use your API on the Tutorials tab. Adding tutorials helps developers understand how to use the API and may increase the chances of them subscribing to your API. You can find this tab by going to your API listing and clicking on the Tutorials tab. For more information regarding tutorials, see Tutorials.

The tutorials array contains objects with the following three fields.

📘

Tutorials tab must be enabled

If you don't see a Tutorials tab, it may need to be enabled for your Enterprise Hub. Please contact your Rapid representative.

Example of the x-documentation object:

"x-documentation": {
     "readme": "This is my readme for the main api",
     "spotlights": [{
       "title": "main-spotlight",
       "description": "This is main spotlight description...",
       "link": "https://en.wikipedia.org/wiki/Image"
     },
     {
       "title": "other-spotlight",
       "description": "This is another spotlight description...",
       "link": "https://en.wikipedia.org/wiki/Computer"
     }],
     "tutorials": [{
       "title": "main-tutorial",
       "description": "This is main tutorial description...",
       "link": "https://dytvr9ot2sszz.cloudfront.net/wp-content/uploads/2019/05/1200x628_logstash-tutorial-min.jpg"
     },
     {
       "title": "other-tutorial",
       "description": "This is other tutorial description...",
       "link": "https://i.ytimg.com/vi/B6nLuyVOk4k/maxresdefault.jpg"
     }]
   },

Updating an API

The following fields can be updated via the OpenAPI document. Other editable fields can be updated using the user interface.

• info.description
• info.version
• info.termsOfService
• info.x-version-lifecycle
• info.x-category
• info.x-long-description
• x-gateways
• x-documentation.readme

Example simple OpenAPI document

This is a simple OpenAPI document containing the minimum fields needed to successfully import a document into your Hub using the Platform API. You can use this document as a test of the basic functionality, assuming there are no tags/badges set to "Make Required for Providers" in the Admin Panel.

{
   "openapi": "3.0.0",
   "info": {
     "title": "Test 1XX",
     "version": "1.0.1",
     "x-category": "Other"
   },
   "paths": {
    "/list": {
      "get": {
        "description": "Returns a list of stuff",
        "responses": {
          "200": {
            "description": "Successful response"
          }
        }
      }
    }
  }
 }

Example larger OpenAPI document

{
   "openapi": "3.0.0",
   "info": {
     "title": "Test 2XX",
     "description": "This is the short description",
     "version": "1.0.1",
     "x-category": "Other",
     "x-long-description": "This is the LONG description",
     "x-website": "https://rapidapi.com",
     "x-public": false,
     "x-thumbnail": "https://rapidapi-prod-apis.s3.amazonaws.com/72f81d15-39c4-46c4-a940-ae94fbb0b9c6.png",
     "x-version-lifecycle": "active",
     "x-collections" : ["Collection Name"],
     "termsOfService": "https://policies.google.com/terms?hl=en-US",
     "x-badges": []
   },
   "x-documentation": {
     "readme": "This is my readme for the main api",
     "spotlights": [{
       "title": "main-spotlight",
       "description": "This is the main spotlight description...",
       "link": "https://en.wikipedia.org/wiki/Image"
     },
     {
       "title": "other-spotlight",
       "description": "This is another spotlight description...",
       "link": "https://en.wikipedia.org/wiki/Computer"
     }],
     "tutorials": [{
       "title": "main-tutorial",
       "description": "This is the main tutorial description...",
       "link": "https://dytvr9ot2sszz.cloudfront.net/wp-content/uploads/2019/05/1200x628_logstash-tutorial-min.jpg"
     },
     {
       "title": "other-tutorial",
       "description": "This is other tutorial description...",
       "link": "https://i.ytimg.com/vi/B6nLuyVOk4k/maxresdefault.jpg"
     }]
   },
   "x-gateways":[{ "url": "rapidapi.com" }],
   "servers": [{ "url": "https://example.com", "description": "Base URL" }],
   "tags": [{ "name": "users" }],
   "paths": {
     "/users/{id}": {
       "get": {
         "tags": ["users"],
         "parameters": [
           {
             "name": "id",
             "in": "path",
             "required": true,
             "schema": { "type": "number", "default": 1 }
           }
         ],
         "operationId": "/users/{id}",
         "description": "Endpoint for fetching users",
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": { "type": "object" }
               }
             },
             "description": ""
           }
         }
       }
     }
   }
 }