API Directory Field Description

Overview

This document provides field/section descriptions for the API Directory. This field description focuses on fields encountered when creating and testing an API. For steps on how to create and test an API, see Create and Test an API.

Field/Section Descriptions

Field/Section Description
Title of API The name which the API consumers see when the API is published.
Name of the API The internal name used for processing the API in the system. Users will not see this name.
Base Path The starting path of the resource url you wish to have for the API. The base path is unique for each API and API developers are advised not to have conflicting base paths while developing APIs.
Version Version is synonymous to the release number of the API. You can have multiple versions of the APIs published, but API developers are advised to always replace the existing version so it doesn’t confuse the consumers.
Terms and License The SLA for the API if the API has a specific one. API developer is responsible for providing this info if applicable.
External Documentation Currently, this feature is not supported in the product.
Host Currently, this feature is not supported in the product.
Consumes The file format of the input accepted by the API from the client. The most used types are application/json and application/xml. Additional MIME types can be specified in Additional Media types section if applicable for the API.
Produces The file format of the response sent by the API to the client. The most used types are application/json and application/xml. Additional MIME types can be specified in Additional Media types section if applicable for the API.
Policy Assembly This section is used to formulate the way how the API will interact the API end point url. This may involve specifying the Basic Auth credentials / hardcoding some parameters while invoking the backend etc.
Security Definitions Security Definitions are the restrictions placed on how to access the API. You can define a variety of securities like a clientId / client Secret or a Basic Auth / OAuth security. You may define multiple security definitions but can apply only one or two based on the requirement. Its is highly recommended to use the OAuth 2 security as one of the security definitions along with any other ones the API Developer deems fit.
OAuth Refer to API Overview for more information.
Token Url Token url is the Oauth token provider url which will generate the access token based on the client id/secret and scope.
Scope Scope refers to what information the client app can retrieve using the OAuth token that is generated using this scope. Normally a scope is used per API / a resource within an API. The client application requests a OAuth2 access token using the scope name as a required parameter. The access token thus generated will be able to get the data only for the API for which it is binded/enabled.
Security

This section enables the API developer to choose the combination of security definitions he/her has defined in the earlier section. The security can have multiple combinations. The API access is granted even if one of the combinations is satisfied.

For Example:
API Developer can define two options as security:

  • Option1: Client Id/ Client Secret.
  • Option2: Client Id / Oauth 2 with scope.

Now if the client sends just the client Id/ Secret as parameters, the API can be accessible. Alternatively the client can send client Id / OAuth2 access token as parameters and still get the data as it's one of the security options.

Extensions Extensions are the additional processing steps that an API developer may choose to use for an API functionality like transforming the input/output using a custom extension defined within the API Manager. By default no extension is enabled. Refer to Adding an OpenAPI (Swagger 2.0) extension to an API definition (API Manager UI) for more information.
Last Updated: 
Sunday, June 11, 2017