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. Eg: Department
Name of the API The internal name used for processing the API in the system. Users will not see this name. Eg: Department
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. Eg: /bf/department
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. Eg: v1
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. Eg: Description: Department API Documentation URL: Google document UR
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. Eg: Check both application/json and application/xml
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. Eg: Check both application/json and application/xml
Policy Assembly This section is used to formulate how the API will interact the API end point url. This may involve specifying the Basic Auth credentials / hardcoding some parameters while invoking the back-end etc. Refer to API Developer cheat sheet
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. Eg: Client Id and OAuth 2 Security
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. Refer to API Developer cheat sheet
Scope Scope refers to the information the client app can retrieve using an OAuth access token. Normally, one scope is defined per API or a single resource within an API. The client application requests an OAuth access token using the scope name as a required parameter. The access token thus generated will be able to retrieve the data for only that API. Eg: Department
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:

  • Option 1: Client Id/ Client Secret.
  • Option 2: 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. Eg: Enable both Client Id and OAuth 2 security

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.
To visit the API Directory, click here.
Last Updated: 
Sunday, June 11, 2017