Defining and Managing APIs
Asynchronous APIsCreating APIsAPIs are designed to expose application functionality and data for use by consumers and developers, as necessary. A basic API definition influences how efficiently consumers or developers are able to consume and use an API. Core API design considerations are fueled by business drivers, developer and consumer audiences, as well as the available resources. Therefore, a careful consideration of all influencing factors affects the planning and architectural decisions you make while designing and defining your API.
The following figure depicts the various factors that drive the designing and defining of an API.
API Gateway enables organizations to define and manage their APIs. Developer and partner users can use API Gateway’s design and customization capabilities to build, develop, and then publish APIs to a portal for consumption by internal and external API consumers.
The following sections describe the types of APIs that API Gateway supports, the different ways in which you can create APIs, update APIs, create and maintain different versions of an API, and group and tag APIs.
API administrators and users with the appropriate functional privileges can use API Gateway’s capabilities to create and manage APIs, and publish the APIs to Developer Portal or service registries from where they can be consumed.
API Gateway supports the following API types:
Representational State Transfer (REST) Defines a set of architectural principles that allow accessing and manipulating resources by using capabilities already built into HTTP, including uniform and predefined set of stateless operations. These operations and resources are represented by media types. The RESTful framework provides REST APIs based on REST architecture. There are multiple specification formats for REST APIs. In API Gateway, you would create a REST API using one of the supported formats: RAML, Swagger 2.0, OpenAPI 3.0 Specification.
Simple Object Access Protocol (SOAP) Defines a communication method for XML-based message exchange over different transport protocols, such as Hypertext Transfer Protocol (HTTP) and Simple Mail Transfer Protocol (SMTP). This framework provides SOAP APIs based on Web Services Description Language (WSDL).
Open Data Protocol (OData) Defines a set of best practices for the creation and consumption of RESTful APIs. It provides a uniform way to describe both data and the data model. The OData framework provides interoperable OData APIs with a RESTful interface based on OData standards.
GraphQL Defines a query language designed to build client applications by providing a flexible syntax and provides a comprehensive description of data within an API. API Gateway supports proxying an existing GraphQL endpoint and provides API management capabilities to clients like authentication, analytics, and so on. API Gateway supports GraphQL version 16.2.
Asynchronous APIs
API Gateway provides an asynchronous form of API support for REST APIs. The synchronous and asynchronous nature of an API depends on the way how a request sent by an application is processed, and the mode and the time frame in which the data is returned to the client.
The following are the differences between the synchronous and asynchronous APIs.
Synchronous API | Asynchronous API |
---|---|
Synchronous API is used where data or service availability, resources and connectivity are high and requires low latency. | Asynchronous API is used where data or service availability, resources and connectivity are low or over-saturated with demand. |
The client application requests data and waits until it receives a response to proceed with other processes. The expectation is an immediate response | The client application requests data and continues with other processes without waiting for a response. There is no expectation of an immediate response. |
Consider this example of synchronous and asynchronous APIs performing a log purge operation. In this scenario, because there is a wait period for the return of data, synchronous API invocations might time out when the API processes take a significant period of time to complete. The following figure depicts the differences between how a synchronous and an asynchronous API perform the log purge operation.
While creating a REST API, API Gateway provides the capability of defining the callback component with the supported method parameters. For details about creating an API with the callback defiition, see Creating a REST API.
Creating APIs
You can create and manage APIs from the Manage APIs page in API Gateway UI. The page lists all the APIs, their description, and version number. On this page you can create an API, delete an API, view API details, activate or deactivate an API, publish or unpublish an API, view API analytics, group APIs, and add tags to an API.
You can create an API in one of the following ways:
Create an API by importing a definition for an existing API (for example, in Swagger or RAML format) using an API importer.
An API importer generates an API from a URL or an input file in one of the supported formats. For example, the RAML importer installed with API Gateway reads a RAML file and generates a REST API that the RAML definition describes. The importer also uploads the RAML file to the API Gateway repository and links the file to the REST API.Create an API from scratch and set its attributes manually.
The following sections explain in detail about different ways of creating APIs.
Creating an API by Importing an API from a File
No subtopics in thissection
You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.
To create an API by importing an API from a file
Click APIs in the title navigation bar.
A list of available APIs appears.Click Create API.
Select Import API from file.
Click Browse to select a file.
Select the required file and click Open.
The Swagger parser is a self-contained file with no external references and can be uploaded as is. If the RESTful API Modeling Language (RAML) file to be imported contains external references, the entire set of files must be uploaded as a ZIP file with a structure as referenced by the RAML file.
Note- Importing an API fails for an invalid WSDL file.
Type a name for the API name in the Name field.
- If you provide an API name, this overwrites the API name mentioned in the uploaded file and the API is displayed with the name provided.
- If you do not provide an API name, the API name mentioned in the uploaded file is picked up and the API is displayed with that name.
- If you do not provide an API name and the uploaded file does not have an API name mentioned, then the API is displayed as Untitled.
Select the required type.
The available types are OpenAPI , RAML, Swagger, and WSDL, and GraphQL SDL.Provide a version for the API in the Version field.
Select the team to which the API must be assigned in the Team field.
This field appears only when the Team feature is enabled. It displays only the teams that you are a part of. If you have the User Management functional privilege, all teams are displayed. You can select more than one team. To remove a team, click the icon next to the team to be removed.Click Create.
An API is created with default policies.
Creating an API by Importing an API from a URL
No subtopics in thissection
You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.
To create an API by importing an API from a URL
Click APIs in the title navigation bar.
A list of available APIs appears.Click Create API.
Select Importing API from URL.
Type the URL from where the API is to be imported.
Select Protected to make the API a protected API.
Type a name for the API name in the Name field.
- If you provide an API name, this overwrites the API name mentioned in the uploaded file and the API is displayed with the name provided.
- If you do not provide an API name, the API name mentioned in the uploaded file is picked up and the API is displayed with that name.
- If you do not provide an API name and the uploaded file does not have an API name mentioned, then the API is displayed as Untitled.
Provide a description for the API in the Description field.
Select the required type.
The available types are OData, OpenAPI, RAML, Swagger, and WSDL, and GraphQL SDL.Provide a version for the API in the Version field.
Select the team to which the API must be assigned in the Team field.
This field appears only when the Team feature is enabled. It displays only the teams that you are a part of. If you have the User Management functional privilege, all teams are displayed. You can select more than one team. To remove a team, click the icon next to the team to be removed.Click Create.
An API is created with default policies.
Note
- Importing an API fails for an invalid WSDL file.
- Creating an API by importing swagger files from an HTTPS URL that is using self-signed certificates may fail. To workaround this, you can set the system environment variable as:
export TRUST\_ALL=true
, so that the invalid certificates are ignored. Be aware that setting this variable makes the swagger-parser ignore all invalid certificates too. So this workaround has to be used with caution.
- Since the GraphQL API schema does not contain a native endpoint, you must manually update the Native endpoint URL in the API details section and the Endpoint URI in the routing policy after you create a GraphQL API.
Creating an API from Scratch
Overview of creating a REST API from ScratchCreating a REST APIYou can create REST APIs from scratch, meaning that you create the asset and set its attributes manually.
Overview of creating a REST API from Scratch
The Create REST API wizard breaks down the task of creating a REST API from scratch into logical steps. The following figure illustrates the different pages of the wizard:
Basic Information
The Basic Information page includes fields that allow you to identify, categorize, and group an API.
Technical Information
The Technical Information page includes fields that allow you to define one or more server URLs for the API. You can also define and include variables in the URLs.
You can also specify parameters for data that must be included in every request to the API. For example, if you want a specific query parameter to be included in every request, you can add a parameter of the type Query and specify the value that it must include.
Resources and methods
The Resources and methods page includes fields that allow you to define the API resources and methods, including callback methods. In this page, you can add all the resources and their methods that are exposed by the API.
At the resource level, you add a resource by defining the following properties: name, path, and supported methods. You can additionally add parameters for data that must be included in every request to that resource. For example, if the methods in a resource are invoked using URLs that have a query string; you can add a query string parameter that captures the queries sent by the clients.
At the method level, you identify a method by adding an operation id. In addition, you can add tags that help you to categorize and search for similar methods. You can also add parameters at the method level. Similar to the parameters at the API and resource levels, method parameters enable you to capture and process the data that is sent in a particular request. In the case of method parameters, the data in the request for that method is captured and processed.
Method Requests
In the request section of a method, you can define the schema for requests that contain a JSON or XML payload. As a method can support multiple content types, you need to add a content type and then define the schema supported by that content type.
You can enter a schema or select an existing schema or global schema that you have previously added on the Components page, Schemas section. You can also add a sample for the schema that you have added or selected. These samples can be used for API mocking. They can also be used by end users to get a better understanding of the API.
Method Responses
You can define responses for different HTTP status codes. API Gateway gives you the flexibility to define responses for a status codes series (such as the 2XX series or the 4XX series) or for specific response codes, such as 201 or 400.
For each status code in a method response, you define the following:
Response body: you define the response body using the following fields:
Content Type: You can select from any of the content types.
Schema: You can define a schema if the response contains JSON or XML data.
Sample: The samples are used for API mocking. They can also be used by end users to get a better understanding of the API.
Header parameter: You can add a parameter to capture and process a header in the response sent by the native API.
Links: Links allow the developer of the native API to define the relationship and traversal mechanism between a response and other operations. You can include links to other methods that are related to the response. This enables an API client to dynamically navigate the methods that are exposed by the API. For example, a method that returns the temperature in Fahrenheit for a given place may also include links to methods that return: a) the temperature in Centigrade; and b) the temperature of the place on a given day of the year.
NoteYou can define the complete response, or any part of it (response body schema, header parameter, or link), in the Components page; and reuse it wherever required by giving a reference.
Method Callbacks
A callback is an asynchronous API request that originates from the API server and is sent to the client in response to an earlier request sent by that client. APIs can use callbacks to signal an event of interest and share data related to that event. API clients that are interested in an event or data related to that event, include a callback URL in the request they send to the API. For more information about Asynchronous APIs, see Asynchronous APIs.
To enable API Gateway to process callback messages, you must configure the Callback processor settings, as explained in Configuring API Callback Processor Settings.
If your API supports callbacks, you can use API Gateway to process the initial requests, the callback URLs sent by clients, and the response sent by the API—including the callback messages. Clients can provide the callback URL to API Gateway in any of the following ways:
Request header
Query parameter
Request body (if the response body has JSON or XML content)
You must define the relevant parameter to capture the callback URL to process it. API Gateway can wrap the client callback URLs with its own URL to process these requests if the callback URL path defined in the following formats. Otherwise, API Gateway sends the requests received from client as it receives it.
Format | Description |
---|---|
{$request.query.param-name} | Where param-name is the name of the query parameter that contains the callback URL. |
{$request.header.header-name} | Where header-name is the name of the header that contains the callback URL. |
{$request.body#/field-name} | Where field-name is a field in the request body. If the field is an array, use the syntax {$request.body#/field-name/arrayIndex}, where arrayIndex is the index of the callback URL in the array. |
${response.header.header-name} and ${response.headers.header-name} | Where header-name is any of the valid header. |
${request.query.param-name} | Where param-name is the name of the query parameter that contains the callback URL. |
${response.payload.jsonPath[queryValue]} | Where queryValue is a valid JSON path expression. |
${response.payload.xpath[queryValue]} | Where queryValue is a valid XPath path expression. |
If you have enabled API Gateway to process callback messages, API Gateway wraps the callback URL provided by the client and sends an API Gateway URL to the native API. When the native API invokes the same callback URL, API Gateway processes the response and applies the policies that you have defined.
API Gateway can apply the following policies on the callback messages:
Response Transformation
Validate API Specification
Data Masking
Log Invocation
These policies are applied to the immediate responses of an API request and to all its callback requests. These policies are enforced against callback request payloads.
API mocking
API mocking allows you to simulate a native API that is not available. The mock response that you define is returned to the client that invokes the API, if the native API is not available. API mocking is not available while you are creating an API. To use API mocking, you must edit the API after creating it and enable API mocking.
You must enable API mocking for an API after creating the API. For more information about API mocking, see API Mocking.
Components
The Components page allows you to add reusable elements that you can use in other pages of the wizard. You can reference these global elements using the $ref
variable. You can add the following global elements:
Schemas: The schema specified here can be reused in the resource and method specifications across multiple methods and resources.
Parameters: You can define parameters that can be used as API, resource, and method parameters.
Headers: You can define parameters that can be reused as header parameters at the API, method, and response levels.
Examples: You can add examples that can be reused as samples across operations in the API.
Links: You can define links that can be reused in responses. For more information about links, see Links within Method Responses above.
Callbacks: You can define callback methods in this page and include them in the callback section of the methods that use it. For more information about callbacks, see Method Callbacks above.
Request Bodies: You can define request bodies in this page and reuse them in methods. A request body includes the content type, a schema, and a sample.
Responses: You can define responses in this page and reuse them in methods. A response includes the content type, a schema, and a sample. It can also include header parameters and links.
Documentation
In the view mode, the Documentation page provides the following links:
Links to the Swagger, RAML, and OpenAPI versions of the API on the Integration Server.
Links to download the API in the three different formats: Swagger, RAML, and OpenAPI.
In the edit mode, the Documentation page allows you to add a file that contains any documentation that you want to include with the API. This file is accessible only from API Gateway.
Creating a REST API
You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.
You can create a REST API from scratch by providing the basic information, technical information, and defining the resources and methods as required.
To create a REST API from scratch
Click APIs in the title navigation bar.
A list of all existing APIs appears.Click Create API.
Select Create from scratch.
Select REST.
Click Create.
The Basic information page of the Create REST API wizard appears.Provide the following information in the Basic information section:
Field Description Name Name of the API. Version Version of the API being created. Maturity state Maturity state of the API. Available values are: Beta, Deprecated, Experimental, Production, Test.
The available values depend on the Maturity states configured in theapiMaturityStatePossibleValues
property under Administration > Extended settings section.API grouping Group under which the API would be categorized.
Available values are: Finance Banking and Insurance, Sales and Ordering, Search, and Transportation and Warehousing.
The available values depend on the groups configured in theapiGroupingPossibleValues
property under Administration > Extended settings section.Tags Keywords for categorizing, identifying, and organizing APIs. You select from the list of existing tags or create new tags. Description Description of the API. Click Continue to provide technical information for this API >.
NoteClick Save to save the API at this stage and close the Create REST API wizard.Enter the details of the servers that serve the API in the Add server details section.
a. Click Add server and provide a Server URL and Description.
You can include variables in the server URL by enclosing them in curly braces. These variables are added to the list of variables. However, you have to edit these variables to add a default value, and optionally one or more values and a description.b. Click Add variables and provide the following values:
Name
Description
Default
Value
NoteClick + to add the value that you have entered.
c. Click Add to add the variable.
Click Add Parameter and provide the following information to add the API-level parameters.
Field Description Name Name of the parameter. Description Description of the parameter. Type Specifies the parameter type.
Available values: Query-string, Header, Cookie.Data type Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, File.Required Specifies the parameter is required if selected. Repeat Select if the input parameter is of type array. Value Specifies the possible values. NoteYou need to define parameters only for data that you want API Gateway to process.Type a Service registry display name.
By default, the API will be displayed in service registries with the name: APIName_Version. If you want the API to be displayed in the service registries with a different name, you can type the name here.Click Continue to provide Resource and methods for this API>.
NoteClick Save to save the API at this stage and close the Create REST API wizard.Add resources to the API using the Resources and methods page:
a. Click Add Resources and provide the following information:
Field Description Resource name Name of the resource.
This is the display name of the resource and resource path is used for execution.Resource path Specifies the path of the resource.
The resource path should contain a “/”.Description Description of the resource. Supported methods Select the methods that are supported by the API: GET, HEAD, POST, PUT, DELETE, PATCH. b. Click Add. The resource is added. You can add multiple resources, if required.
c. Add Tags.
d. Click Add Resource Parameter and provide the following information:
Field Description Name Name of the parameter. Reference If you want to reuse a global parameter defined on the Components page, select the parameter from the drop-down list. Description Brief description of the parameter. Type Specifies the parameter type.
Available values: Path, Header, Query-string, Cookie.Data type Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, File.Required Specifies the parameter is required if selected. Repeat Select if the input parameter is of type array. Value Specifies the possible values for the parameter. e. Click + Add to add the resource parameter.
For each supported method that you have added for a resource, enter the following information:
a. Common information
Field Description Description Type a description for the operation. OperationId Type an operation ID. Tags Type or select the keywords that you want to add to the operation. b. Method parameters
Field Description Name Name of the parameter. Reference If you want to reuse a global parameter defined on the Components page, select the parameter from the drop-down list. Description Brief description of the parameter. Type Specifies the parameter type.
Available values: Query-string, Header, Cookie.Data type Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, File.Required Specifies the parameter is required, if selected. Repeat Select if the input parameter is of type array. Value Specifies the possible values for the parameter. c. Requests: You can select an existing global request defined on the Components page or specify a new request.
To enter a new request, select New request and provide the following information:
To add a new request that has to be processed, click Add Request + and provide the following information:
Content type: Select one and click Add.
Schema: Type a schema in the text box or select an existing schema from the Select a Schema list. You can also click Add global schema and create a new global schema on the Components page. After creating the global schema you can select it from the Select a Schema list.
Sample: Type a sample for selected schema. This sample can be used for API mocking, if required.
To use an existing global request to process a request, select Global request and provide the following information:
Name:
Reference: select one and click Add.
d. Responses: First, add a status code using the Status Code drop-down list.
Next, click on the status code to select it. For the selected status code, you can select an existing global response defined on the Components page or enter a new response. To enter a new response, select New response and define the response by adding a schema and a sample for the response body, header parameters, and links.
NoteYou can also define the response for an HTTP status code series, such as 2** or 4**.
To define a new response for the selected status code, click Add response + and provide the following information:
Content type: select one and click Add.
Schema: Type a schema in the text box or select an existing schema from the Select a Schema list. You can also click Add global schema and create a new global schema on the Components page. After creating the global schema you can select it from the Select a Schema list.
Sample: Type a sample for selected schema. This sample can be used for API mocking, if required.
To use an existing global response, select Global response and provide the following information:
Name: Name of the response.
Reference: select one and click Add.
To add a header parameter, click + Add header parameter and enter the following information to add a header parameter:
Field Description Name Name of the parameter. Reference If you want to reuse a global parameter defined on the Components page, select the parameter from the drop-down list. Description Brief description of the parameter. Type Specifies the parameter type.
Available values: Header.Data type Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, File.Required Specifies the parameter is required if selected. Repeat Select if the input parameter is of type array. Value Specifies the possible values for the parameter. Click + in the Value text box to add a value to the list, and click Add to add the header.
To add a link, click + Add links and enter the following information to add a link:
Name: Name of the link.
Description: Description for the link.
Link: You can add a new link or select an existing global link that is defined on the Components page.
To add a new link, select New link and enter the following information:
Type: Select OperationId for local operations only. OperationRef can be used for both local and external operations.
Value: If Type is OperationRef, provide a reference to the target operation using the JSON Reference syntax (using by the $ref keyword); and if the Type is OperationId provide the OperationId of the target operation.
Parameters: Specify the parameters of the target operation that are required to follow the link. Enter a Name and Value, and click Add.
Request body: Enter a request body only if the target operation has a body. Define the contents of the body of the target operation.
To include an existing global link, select Global link and then select an existing global link from the Reference drop-down list.
e. Callbacks: You can add the callbacks that are supported by the method.
You can add new callbacks and select existing global callbacks.NoteFor more information about using callbacks to develop asynchronous APIs, see Asynchronous APIs. For more information on defining and using callbacks in API Gateway, see Overview of Creating a REST API from Scratch.To specify a new callback, click + Add callbacks and define the callback:
Name: A name for the callback resource.
Click + Add resources and provide details of the API that serves as the callback API.
NoteThe user interface and procedure for defining a callback is similar to defining a resource and methods within the resource.To include a global callback defined on the Components page, provide the following information:
Name: Name of the callback resource.
Reference: If you want to reuse a global callback defined on the Components page, select the callback from the drop-down list and click Add.
Click Continue to provide Mocking information for this API>.
NoteClick Save to save the API at this stage and close the Create REST API wizard.
The API mocking page appears. API mocking is not enabled for a new API: You must edit the API and enable API mocking after creating the API.
Click Continue to define API components for this API>.
Alternatively, you can click Components.NoteClick Save to save the API at this stage and close the Create REST API wizard.Define the reusable elements that you want to reuse in other pages of the Create REST API wizard.
An API may have several elements that are common across resources and methods, such as schemas for response bodies. You can place such common elements in the Components section and reference them using the $ref alias.a. In the Schemas section, click + Add schema and provide the following information:
Field Description Name Name of the schema. Schema type Specifies the schema type.
Available types: Inline schema and External schema.Value Specifies the value for the schema type selected.
For an inline schema, type the request and response values.
For an external schema, click Browse to upload a schema.Click + Add to add the schema component.
b. In the Parameters section, click + Add parameter and provide the following information:
Field Description Name Name of the parameter. Description Description of the parameter. Type Specifies the parameter type.
Available values: Path, Query-string, Header, and Cookie.Data type Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, and File.Required Specifies the parameter is required if selected. Repeat Select if the input parameter is of type array. Value Specifies the possible values for the parameter. Click + Add to add the parameter component.
c. In the Headers section, click + Add header and provide the following information:
Field Description Name Name of the header. Description Description of the header. Type Specifies the header type. This is fixed as Header for headers. Data type Specifies the data type.
Available values: String, Date, Date time, Integer, Double, Boolean, and File.Required Specifies the header is required if selected. Repeat Select if the input parameter is of type array. Value Specifies the possible values for the header. Click + Add to add the header component.
d. In the Examples section, click + Add examples and provide the following information:
Field Description Name Name of the example. Summary Description of the example. Value The content of the example. Click + Add to add the example component.
e. In the Links section, click + Add links and provide the following information:
Field Description Name Name of the link. Description Description of the link. Type Specifies the link type: OperationId or OperationRef. Value Path to the target operation or a reference to the target operation. Parameter name Name of the parameter that needs to be passed as a parameter to the target operation. Parameter value Value for the parameter. Click + Add to add the parameter. You can additional parameters if required. Request body Payload of the request sent to the target operation. Click Add to add the link component.
f. In the Callbacks section, click + Add callback and provide the following information:
i. Type a name for the callback.
ii. Click + Add resources.
iii. Type the Callback path.
iv. Select the supported methods.
v. Click Add.
vi. For each method that you have just added, complete the next two steps.
vii. Click + Add Resource Parameter and add the required resource parameters.
The procedure for adding resource parameters is given in Step 11d.viii. Define the selected methods. The procedure for defining methods is given in Step 12.
g. In the Request Bodies section, click + Add request and provide the following information:
Field Description Name Name of the request. Content type Select a content type from the list. Schema You can also select an existing schema. Sample Type a sample of the schema. Click Add to add the request component.
h. In the Responses section, click + Add Response and provide the following information:
Field Description Name Name of the response. Content type Click Add. Schema You can also select an existing schema. Sample Type a sample of the schema. Header Parameter Click + Add Header Parameter and provide the required information. Then, click + Add to add the header parameter. Links Click + Add Links and provide the required information. Then, click Add to add the link. Click Add to add the response component.
Click Continue to provide API documents for this API>.
NoteClick Save to save the API at this stage and close the Create REST API wizard.The Documentation page appears.
Type a display name and click Browse to select a file.
Click + Add to upload the file and add a new row.
Click Save to save your changes and create the API.
Viewing API List and API Details
REST API DetailsSOAP API DetailsOData API DetailsGraphQL API DetailsYou can view the list of registered APIs, activate, delete, or view analytics of a specific API in the Manage APIs page. In addition, you can view API details, modify API details, activate and deactivate an API in the API details page.
Click APIs in the title navigation bar.
A list of all registered APIs appears. The APIs are sorted based on their names. When there is more than one API with same name, they are sorted based on their system versions. The Date field next to the Version field displays the API creation date.
You can also perform the following operations in the Manage API page:Filter APIs by Type, Activation status, or Team. Select the required API type, status, or team to view the APIs based on the provided filters.
NoteThe Team filter is applicable only if you have enabled the Teams feature.Activate an API by clicking that denotes an inactive state.
Once an API is activated, the Gateway endpoint is available which can be used by the consumers of this API.Deactivate an API by clicking the status icon that denotes an active state.
Delete an API by clicking the Delete icon.
View API analytics by clicking the Analytics icon.
Publish or Unpublish an API by clicking Publish and the Unpublish icons respectively.
Click any API to view API details.
The API details page displays the basic information, technical information, resources and methods, and specification for the selected API. This page allows you to edit some of the API details. Also, this page provides options to activate/deactivate an API. Click to export, enable or disable mocking, update, and create new version operations.The list of registered applications is sorted by name in ascending order and you can view the total count of registered applications. If the list of registered applications is long, then the applications are distributed in more than one page. You can navigate between the pages by selecting the page numbers provided below the grid.
REST API Details
The REST framework enables you to model APIs conforming to the (Resource Oriented Architecture) ROA design. For example, you might model an API that serves to expose the web service data and functionality as a collection of resources. Each resource is accessible with unique Uniform Resource Identifiers (URLs). In your API, you expose a set of HTTP operations (methods) to perform on a specific resource and capture the request and response messages and status codes that are unique to the HTTP method and linked within the specific resource of the API.
The API details view for a REST API displays the details of the API such as Basic and Technical information, Resources and methods, API mocking details, and specifications. You can also view the scopes associated, policies enforced, registered applications and the API-specific analytics.
The table lists the API details displayed for the API:
Field | Description |
---|---|
Basic information | Displays the information about the API, such as Name, Version, Owner of the API, the teams that the API is assigned to, status of the API whether its is Active or Inactive, the maturity state of the API, the date on which the API was created and a brief description of the API. |
Technical information | Displays the native endpoints of the API. |
Resources and methods | Displays a list of resources or methods available in the API sorted by resource/pathname. The list of resources are displayed in sorted order of the path names. Click each resource to view the corresponding HTTP methods, along with a summary. Below each of these methods, details such as parameters and response codes are displayed. |
API mocking | Details are visible only when API mocking is enabled. Displays a list of mocked responses for the operations in the API, custom IS service list and conditions along with its mocked response. |
Components | Displays the schemas defined at the API level. |
Documentation | Displays the definition of the API in different formats. |
Various tabs displayed in the API details page display the following details:
The Scopes tab lists the scopes available for the API.
The Policies tab displays the policies enforced for the API.
The Mashups tab displays the mashups defined in the API.
The Applications tab displays all the applications registered with the API.
The Analytics tab displays the API-specific analytics for the time interval selected.
You can perform the following operations from the API details page:
You can enable API mocking by clicking the Enable mocking button. If API mocking is enabled, you can disable it by clicking the Disable mocking button. This option is available when the API is in the deactivated state.
You can update an API by importing from file or from URL by clicking the Update button. This option is available when the API is in the deactivated state.
You can create a new version of the API by clicking the Create new version button.
You can modify details of an API by clicking the Edit button. This option is available when the API is in the deactivated state.
You can activate an API by clicking the Activate button. If the API is already activated, you can deactivate it by clicking the Deactivate button.
SOAP API Details
The API details view for a SOAP API displays the details of the API such as Basic and Technical information, Operations available, REST transformation details, API mocking details, and specifications. You can also view the scopes associated, policies enforced, registered applications and the API-specific analytics.
The table lists the API details displayed for the API:
Field | Description |
---|---|
Basic information | Displays the information about the API, such as Name, Version, Owner of the API, the teams that the API is assigned to, status of the API whether its is Active or Inactive, the maturity state of the API, the date on which the API was created and a brief description of the API. |
Technical information | Displays the native endpoints of the API. |
Operations | Displays a list of operations available in the API and they are sorted alphabetically. Operations are displayed along with their type of binding (SOAP 11 , SOAP 12, and other HTTP methods). Click each method to view details such as input, output, and fault messages. |
REST transformation | Displays a list of operations exposed as REST resources and they are sorted alphabetically. Operations are displayed along with their type of binding. Click each method to view details such as input, output, and fault messages. |
API mocking | Details are visible only when API mocking is enabled. Displays a list of mocked responses for the operations in the API, custom IS service list and conditions along with its mocked response that contains the status code and mock payload details. |
Documentation | Displays the definition of the API in different formats. |
Various tabs displayed in the API details page display the following details:
The Scopes tab lists the scopes available for the API.
The Policies tab displays the policies enforced for the API.
The Applications tab displays all the applications registered with the API.
The Analytics tab displays the API-specific analytics for the time interval selected.
You can perform the following operations from the API details page:
You can enable API mocking by clicking the Enable mocking button. If API mocking is enabled, you can disable it by clicking the Disable mocking button. This option is available when the API is in the deactivated state.
You can update an API by importing from file or from URL by clicking the Update button. This option is available when the API is in the deactivated state.
You can create a new version of the API by clicking the Create new version button.
You can modify details of an API by clicking the Edit button. This option is available when the API is in the deactivated state.
You can activate an API by clicking the Activate button. If the API is already activated, you can deactivate it by clicking the Deactivate button.
Exposing a SOAP API to Applications
An active SOAP API exposes its WSDL with a couple of adaptions:
The service name becomes the selected API Name.
Custom endpoints as well as URL aliases appear with separate port elements.
The HTTP and HTTPS endpoints are exposed if they meet the respective settings in the Transport policy.
The SOAP and SOAP12 entries are exposed if they meet the respective settings in the Transport policy.
Only enabled operations are exposed.
The values from the Inbound Auth - Message policy are integrated into the WSDL as ws:Policy entries. Note that the original ws:Policy entries from the importing WSDL are not considered.
OData API Details
Open Data Protocol (OData) enables the creation of REST-based APIs, which allow resources to be exposed as endpoints and identified using the Uniform Resource Identifiers (URIs). In general, OData is represented by an abstract data model called Entity Data Model (EDM). This Entity Data Model allows Web clients to publish and edit REST services and their resources using simple HTTP messages. OData leverages the principles of HTTP, REST and ATOM, and combines the simplicity of REST and SOAP metadata definitions to describe service interfaces, data models, and semantics.
API Gateway supports OData V4 and V2 services.
The API details view for a OData API displays the details of the API such as Basic and Technical information, OData entity sets, singletons, function imports, actions imports and specifications. You can also view the policies enforced, registered applications and the API-specific analytics.
The API Gateway UI exposes only OData navigation properties to visualize the resource path structure of OData APIs. Any other OData property is not displayed.
- Requesting a Derived Entity
- Requesting a Derived Entity Collection
- Filter on Derived Type
Operations on Derived Types are rejected by API Gateway.
The table lists the API details displayed for the API:
Field | Description |
---|---|
Basic information | Displays the information about the API, such as Name, Version, the teams that the API is assigned to, status of the API whether its is Active or Inactive, the date on which the API was created, and a brief description of the API. |
Technical information | Displays base URL of the API and the OData version supported. |
OData entity sets | Displays a list of OData entity sets. An entity set element represents a single entity or a collection of entities of a specific entity type in the data model. The list of entity sets is sorted alphabetically. Click each entity set to view the resource path, entity type, resource parameter details, and the corresponding HTTP methods. The entity types are structured records consisting of named and typed properties and key properties whose values uniquely identify one instance from another. |
OData singletons | Displays a list of OData singletons. Singletons are single entities which are accessed as children of the entity container. The list of singletons is sorted alphabetically. Click each singleton to view the resource path, entity type, the corresponding HTTP methods, and the navigation properties that allow navigation from an entity to related entities. The OData navigation property has an impact on the resource structure. This property is represented as an OData Resource and denoted as OData Navigation properties inside the OData Resources profile. There is no restriction to the number of levels you can drill down |
OData function imports | Displays a list of OData function imports. The Function Import element represents a Function in an entity model. The list of OData function imports is sorted alphabetically. Click each function import to view the resource path, entity type, and the corresponding HTTP methods. |
OData action imports | Displays a list of OData action imports. The Action Import element represents an Action in an entity model. The list of OData action imports is sorted alphabetically. Click each action import to view the resource path, entity type, and the corresponding HTTP methods. |
Documentation | Displays the definition of the API in different formats. The metadata document. The metadata document describes the Entity Data Model that is, the structure and organization of the OData service resources exposed as HTTP endpoints by that particular service. This document describes the entity types, entity sets, functions and actions. |
Various tabs displayed in the API details page display the following details:
The Policies tab displays the policies enforced for the API.
The Applications tab displays all the applications registered with the API.
The Analytics tab displays the API-specific analytics for the time interval selected.
You can perform the following operations from the API details page:
You can update an API by importing from URL by clicking the Update button. This option is available when the API is in the deactivated state.
You can create a new version of the API by clicking the Create new version button.
You can modify details of an API by clicking the Edit button. This option is available when the API is in the deactivated state. Only the following properties of an OData API can be modified:
Name
Description
Version
API group
Maturity state
For updating the OData entity sets, singletons, function imports and action imports a new import has to be performed.
You can activate an API by clicking the Activate button. If the API is already activated, you can deactivate it by clicking the Deactivate button.
GraphQL API Details
API Gateway supports proxying an existing GraphQL endpoint and provides API management capabilities to clients like authentication, analytics, and so on. The GraphQL APIs can be accessed using the HTTP GET and POST methods. You can create and deploy a GraphQL API using the API Gateway UI or REST endpoints.
The following table lists the features that API Gateway supports for GraphQL.
GraphQL Features | Supported |
---|---|
Basic GraphQL concepts:
|
Yes |
Root operations for resources:
|
Yes |
Root operations for resources: Subscription | No |
Input and output data types:
|
Yes |
The following table lists the API Gateway-specific features that are not supported for GraphQL API.
API Gateway Features for GraphQL | Supported |
---|---|
API tagging | No |
API mocking | No |
Policy scopes | No |
Packages and plan | No |
Adding or updating GraphQL schema types | No |
Publishing GraphQL API to Developer Portal | No |
The API details view for a GraphQL API displays the details of the API such as basic and technical information, operations available, and specifications. You can also view the policies enforced, registered applications, and the API-specific analytics.
The table lists the API details displayed for the API:
Field | Description |
---|---|
Basic information | Displays the information about the API, such as Name, Version, Owner of the API, the teams that the API is assigned to, Active or Inactive status of the API , the maturity state of the API, the date on which the API was created, and a brief description of the API. |
Technical information | Displays the following endpoints of the API:
|
Operations | Displays a list of operations available in the API sorted alphabetically. Operations are displayed along with their type (Query and Mutation). |
Documentation | Displays a list of specifications for the API. |
Various tabs displayed in the API details page display the following details:
- The Policies tab displays the policies enforced for the API.
- The Applications tab displays all the registered applications with the API.
- The Analytics tab displays the API-specific analytics for the time interval selected.
You can perform the following operations from the API details page:
- You can export an API using the Export button.
- You can update an API by importing from file or from URL by clicking the Update button. This option is available when the API is in the deactivated state. For more information about updating APIs, see Updating APIs.
- You can create a new version of the API by clicking the Create new version button. For more information about versioning APIs, see Versioning APIs.
- You can modify details of an API by clicking the Edit button. This option is available when the API is in the deactivated state. For more information about modifying API details, see Modifying API Details.
- You can activate an API by clicking the Activate button. If the API is already activated, you can deactivate it by clicking the Deactivate button. For more information about activating API, see Activating an API
Searching Data
No subtopics in thissection
The search feature in API Gateway is a typeahead search—a simple and easy to use search facility where you can type the text of interest to search. You can search for all items that contain one or more specified keywords (that is, text strings) in the item’s properties. Some of the properties are name, description, version, key, value, and so on in the API.
You can search for the following types of data as shown in the image.
To search for an item, simply type a string in the search box in the title navigation bar. A list of search result is displayed directly below the Search box. The number of matches found are displayed in five sections depending on the type they fit in: APIs, Application, Alias, Packages, and Plans. A minimum of five search results are displayed in each category. If there are no results as per the search string typed, a message displays saying so.
If you find what you are searching for in the search result box, click on it to view the details. You are navigated to the specific page that displays more information. For example, if you are searching for an API and click the displayed result, you are navigated to the specified API details page. If you are searching for an application and click the displayed result, you are navigated to the specified Application details page.
If you want to see all the search results click Show all results in the search result box. The Advanced search page is displayed. This is a dedicated page that displays extensive search results. In the Advanced search page, you can search or filter the results in the following ways: by type or keyword.
By type: Select one or more types in the left navigation pane to see search results pertaining to the selected types. For example, if you select the type APIs, all the APIs that have the specified string is displayed.
By keyword: Type a keyword in the Search by keyword field, all the search results containing the specified keyword are displayed in the list. For example, if you type the keyword
petstore
, all search results containing thepetstore
would be filtered and displayed.
NoteSearch by keyword will not show any search results, if the field names have any special characters. The following special characters are not supported - ! ? & # $ * % : ; = ‘ “ ( ) / \ < >
The fields that does not support special characters are as follows:
- Maturity state
- Scope name
- Scope description
- API Operations info name
- API Resource path
- API Tags
- Application identifiers named values
- User Login ID
- User First name
- User Last name
- OAuth scope name
- OAuth Scope description
For example, if an API has a tag name Test-001, and you search APIs with the tag name Test-001, you will not get any search results.
You cannot search for REST resources and methods in a REST API. The search function only works for the name and description of the REST API. For example, you can search for a REST API namedLibraryAPI
. But you cannot search for a REST resource namedbook
or a REST methodPOST
within the REST API. However, the search function works for name, description, and operations of SOAP APIs.You cannot search for resources and methods of an OData API.
Filtering APIs
No subtopics in thissection
You can filter APIs based on the API type or the activation status of the API.
To filter APIs
Click APIs in the title navigation bar.
A list of all registered APIs appears.You can filter APIs based on the following filter options.
You can use a combination of these options to filter the APIs.Type. Select REST, SOAP, OData, GraphQL or all to filter APIs by type.
Activation status. Select Active or Inactive to filter APIs by their activation status.
Team. This filter is applicable only if you have enabled the Teams feature. Select the teams listed to filter APIs by their association with the teams selected.
Active endpoints. Select API Gateway, or Microgateway to filter APIs by their active endpoints available.
Click Apply filter.
The filtered list of APIs is displayed. You can click Reset to reset the values to the original values.
Configuring the Number of APIs listed on a Page
No subtopics in thissection
You can configure the number of APIs that get listed per page in the Manage APIs or the Manage applications page. In each of these pages, you can use the pagination bar at the bottom of the page to navigate from one page to another, the first page, or the last page when there are more than 20 APIs in the list. To change the number of APIs listed in a page, select the required number in the Show # results per page field in the pagination bar at the bottom of the page. The API list now displays only those many APIs in one page as specified. For example, if you select Show 10 results per page, only 10 APIs are listed in one page.
This configuration that you change through the drop down is maintained as long as you are logged in to API Gateway.
The value is set in the drop down is applicable for both APIs and applications listing. For example, if you change the show results to 10 in the Manage APIs drop down, then the number is retained for Manage applications page as well.
Modifying API Details
No subtopics in thissection
You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.
You can modify API details, as required, from the API details page.
To modify API details
Click APIs in the title navigation bar.
A list of all registered APIs appears.Click the required API.
The API details page appears.Click Edit.
NoteIf the API is in the active state, you cannot modify the name and version of the API. The API mocking section is unavailable for any changes.Modify the information as required.
Click Save.
NoteIf the API is in the active state when you modify API details, the active API is replaced with the modified API.
The modified APIs do not become effective for ongoing requests.
Updating APIs
Updating an API by Importing an API from a FileUpdating an API by Importing an API from a URLYou can update the definition of an existing API by uploading WSDL, Swagger, or RAML file or URL. The uploaded file can also be in a ZIP format. When an API is updated, it retains the Expose to consumers settings, the existing scope definitions, the configured policies, and the REST-enabled path configurations for SOAP API. You can also edit an API using the Edit option for minor edits, whereas the update feature helps you to overwrite the complete API definition using a file or a URL at the same time.
You can update an active API. You cannot modify the name and version of an API while updating an active API.
You can update an existing API in the following ways:
By importing an API definition from a file.
By importing an API definition from a URL.
Updating an API by Importing an API from a File
You must have the API Gateway’s manage APIs or Activate/deactivate APIs functional privilege assigned to perform this task. You can not update an API by importing an API from a file if the API is in the active state.
To modify API details
Click APIs in the title navigation bar.
Select the required API from the list of APIs. The API details page for the selected API appears.
Click and select Update. The Update API window appears.
Select Update API by importing from file.
Provide the following information:
Field Description Select file Click Browse to browse to the location of file to be imported and select the required file or ZIP format file. The REST API can be updated using only the Swagger or RAML file type. The SOAP API can be updated using only the WSDL file type. Root File Name If you have selected a file in ZIP format, type the relative path of the main file within the ZIP file. Name Name for the API. Edit or delete the name of the existing API displayed.
- If you provide an API name, this overwrites the API name mentioned in the uploaded file and the API is updated with the name provided.
- If you do not provide an API name, the API name mentioned in the uploaded file is picked up and the API is updated with that name.
Type Select the required type. The available types are RAML, Swagger, WSDL, and GraphQL SDL. - For a REST API, the available options are RAML and Swagger.
- For a SOAP API, the available option is WSDL.
- For a GraphQL API, the available option is GraphQL SDL.
Version Version number of the API. The existing version number of the API is automatically displayed. You can edit or delete the version number. If the version number is deleted and the imported file does not have a version number, then the system automatically assigns a version number during the update.
This overwrites the version of the API.Description Description of the API. The existing description of the API is automatically displayed. You can edit or delete the description. If you delete the description then the description from the imported file is used. Click Update.
The API definition is updated with the latest changes from the file and is displayed in the API details page.
Updating an API by Importing an API from a URL
You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.
To modify API details
Click APIs in the title navigation bar.
Select the required API from the list of APIs. The API details page for the selected API appears.
Click and select Update. The Update API window appears.
Select Update API by importing from URL.
Provide the following information:
Field Description URL Type the URL from which the API is being imported.
Note: The REST API can be updated using only the Swagger or RAML type information that the URL is pointing to. The SOAP API can be updated using only the WSDL file type information that the URL is pointing to. The entity sets, singletons, function imports, and action imports of an OData API can only be updated by a re-import of the OData API definition through the URL.Protected Select this option if you want to import an API from a URL that is password protected. The user name and password fields are displayed using which you can access the provided URL. Username Type the user name required to access the password protected URL. If you have selected the Protected option, this field is displayed. Password Type the password associated with the username. If you have selected the Protected option, this field is displayed. Name Name for the API. The existing name of the API is automatically displayed.
- If you provide an API name, this overwrites the API name mentioned in the file referred by URL and the API is updated with the name provided.
- If you do not provide an API name, the API name mentioned in the file referred to by URL is picked up and the API is updated with that name.
Type Select the required type. The available types are RAML, Swagger, WSDL, OData, and Graph QL SDL.
- For a REST API, the available options are RAML and Swagger.
- For a SOAP API, the available option is WSDL.
- For a OData API, the available option is OData.
- For a GraphQL API, the available option is GraphQL SDL.
Version Version number of the API. The existing version number of the API is automatically displayed. You can edit or delete the version number. If the version number is deleted and the file referred to by URL does not have a version number, then the system automatically assigns a version number during the update.
This overwrites the version of the API.Description Description of the API. The existing description of the API is automatically displayed. You can edit or delete the description. If you delete the description then the description from the file referred to by URL is used. Click Update.
The API definition is updated with the latest changes from the URL and is displayed in the API details page.
Exporting Specifications
No subtopics in thissection
For a REST API, you can export specifications in Swagger and RAML formats to your local system. Similarly, for a SOAP API, you can export a specification in WSDL format to your local system. The exported WSDL is in a ZIP format consisting of the WSDL file whereas for Swagger and RAML the respective files are directly exported. API Gateway supports the following versions:
Swagger 2.0 for a Swagger file
RAML 0.8 for a RAML file
You can export APIs that have been created from scratch or by importing their respective definitions. The Swagger or RAML definition provides the consumer view on a REST API deployed to the API Gateway. Similarly, the WSDL definition provides the consumer view on a SOAP API. Consumer view indicates that the Swagger, RAML, or WSDL definitions contain the API Gateway endpoint and information about those resources and operations, which are exposed to customers.
{"type":"object"}
appears.To export the specification
Click APIs in the title navigation bar.
Select the required API from the list of available APIs.
The API details page for the selected API appears.Click Documentation.
Based on the type of specification that you have selected to export, select any of the following:
Swagger data link to export the Swagger specification.
RAML data link to export the RAML specification.
OpenAPI data link to export the OpenAPI specification.
Artifacts link to export the WSDL specification.
OData meta document link to a zip containing the OData API and metadata document. If the OData API is active, a link to the service document and a link to the metadata document are also displayed.
Schema link to download the GraphQL Schema.
When downloading a zip file the browser prompts you to either open or save the zip file.
Select the appropriate option and click OK.
Attaching Documents to an API
No subtopics in thissection
Pre-requisites:
You must have the Manage APIs functional privilege assigned to perform this task.
You can associate an input document that includes the RAML, Swagger, or WSDL specification, and additional documents such as programming guides, sample code, script files, and project plan with an API. For example, SOAP APIs can contain external documents such as Functional Requirements, Error Messages, Release Notes, and so on.
When attaching a document to an API, keep the following points in mind:
You cannot attach or modify a document to the API if it is in active state. You have to deactivate the API before attaching or modifying it.
API Gateway relies on file extensions to determine a file’s type. When you upload a file from your local machine to the API, be sure the name of the file on your local machine includes a file extension so that API Gateway can determine the file’s type and attach it correctly to the API.
You cannot upload types of files that are restricted for attaching as the input document to the API.
API Gateway provides the ability to restrict certain kinds of files from being uploaded to the API, based on the file extension. The list of restricted files may vary depending on the file extensions configured in the
apiDocumentsRestrictedExtension
property under Administration > Extended settings section.When you try to upload a file type that is restricted, API Gateway prompts you with an error message.
By default, several standard file extensions are blocked in API Gateway, including any file extensions that are treated as executable files by Windows Explorer. The file extensions blocked by default are -
.bat
,.bin
,.dll
, and.exe
.You cannot upload files that exceed the maximum allowed size for the API.
API Gateway provides the ability to limit the maximum file upload size to the API. The maximum file upload size is configured in the
apiDocumentsUploadSizeLimitInMB
property under Administration > Extended settings section.When you try to upload a file that exceeds the maximum file upload size, API Gateway prompts you with an error message.
You can rename an uploaded document. When you rename a document, only the display name of the document could be modified, not the document itself. If you want to modify the document as well, you must delete the file attachment, and attach the latest file.
To attach document
Click APIs in the title navigation bar.
A list of all registered APIs appears.Select the required API.
The API details page appears.Click Edit.
Click Documentation.
Click Browse to select a file and upload it.
Rename the document in the Display Name field as required.
This is the display name of the document in the API details page.Click Add.
The attached document is listed in a table. You can edit and delete the document by clicking the and icons.Repeat steps 5 to 7 for each document that you want to attach to the API.
Click Save.
API Grouping
No subtopics in thissection
You can group APIs based on various categories. Categories help consumers locate APIs easily. For example, if you are offering APIs to help your consumers manage their sales and ordering better, classifying the APIs under Sales and Ordering helps them locate these APIs easily.
The default groups available under which you can group the APIs are Finance Banking and Insurance, Sales and Ordering, Search, and Transportation and Warehousing. If you want to include more groups you can update the property apiGroupingPossibleValues
under Administration > Extended settings that enables API grouping. You can modify the existing list of groups by deleting or adding new group names as comma separated values in this field. Ensure that the group name does not contain a comma as part of the name.
API grouping can be applied in one of these ways:
While creating an API from scratch
While editing an API
You can select one or more groups in the API grouping field. When an API is published to Developer Portal, the published APIs in Developer Portal are grouped as per the group assigned.
API Tagging
Adding Tags to an APITags are words or phrases that act as keywords for categorizing, identifying, and organizing APIs.
In API Gateway, you can assign tags to APIs, and their resources, methods, or operations. Tags help to logically catagorize APIs in different ways, for example, by usage, owner, consuming application, or other criteria. Tags are especially useful when there are multiple APIs of the same type - it enables to quickly identify a specific API based on the tag assigned to it. For example, you can assign the tag GET-Methods
to specific GET methods in different REST APIs, and use it to search for the list of REST APIs with the GET-Methods
tag in API Gateway.
You can use tagging, for example, to do the following:
Tag and untag REST APIs in API Gateway.
Use tags to search for multiple resources and methods across the REST APIs that are available in API Gateway.
Use tags to search for multiple operations across the SOAP APIs that are available in API Gateway.
You can assign one or more tags, remove a tag, and view the tags on the API details page. When a tagged API is published to Developer Portal, the published API in Developer Portal is tagged with the same tag defined in API Gateway.
Adding Tags to an API
Pre-requisites:
You must have the Manage APIs functional privilege assigned to perform this task.
Tags are not automatically assigned to APIs, resources, methods, or operations. You can add one or more tags, and you can remove tags from an API, resource, method, or operation at any time.
You can define a set of consistent tags that meets your needs for each API, resource, method, or operation. Using a consistent set of tags makes it easier to manage the APIs, resources, methods, or operations. You can search the APIs, resources, methods, or operations based on the tags you add.
When tagging an API, keep the following points in mind:
You cannot tag an API if it is in active state. You have to deactivate the API before tagging it.
You can assign tags to the following APIs and its components:
SOAP API. You can assign tags to the SOAP API itself and to its operations.
REST API. You can assign tags to the REST API itself and to its resources, and methods.
REST-enabled SOAP API. You can assign tags to the REST-enabled SOAP API. Also, you can assign tags to the REST resources and methods which correspond to the transformed SOAP operations.
OData API. You can assign tags to the OData API only.
You can assign tags to an API, resource, method, or operation only.
When you delete an API, resource, method, or operation in API Gateway, any tags that were assigned to that API, resource, method, or operation are not deleted.
To tag an API
Click APIs in the title navigation bar.
A list of all registered APIs appears.Select the required API. The API details page appears.
Click Edit.
To add tags to an API, in the Basic information section, do one of the following:
To add an existing tag, select an existing tag from the drop-down list and click
Alternatively, you can search an existing tag by typing characters in the Tags field that displays a list of existing tags that contain the character, select the required tag, and click .To add a new tag, type the new tag and click .
The tag is listed below the Tags. To delete a tag, click the x icon.
.To add tags to resources or methods of a REST API, in the Resources and methods section, locate the required resource or method and do one of the following:
To add an existing tag, select an existing tag from the drop-down list and click
Alternatively, you can search an existing tag by typing characters in the Tags field that displays a list of existing tags that contain the character, select the required tag, and click .To add a new tag, type the new tag and click .
The tag is listed below the Tags. To delete a tag, click the x icon.
To add tags to resources or methods of a SOAP API, in the Operations section, locate the required resource or method and do one of the following:
To add an existing tag, select an existing tag from the drop-down list and click
Alternatively, you can search an existing tag by typing characters in the Tags field that displays a list of existing tags that contain the character, select the required tag, and click .To add a new tag, type the new tag and click .
The tag is listed below the Tags. To delete a tag, click the x icon.
Click Save.
Versioning APIs
Creating New API VersionAPI Gateway supports the creation of new API versions from the existing versions. The new API has the same metadata but with an updated version. The version can either be a number or a string.
The API details page has a drop-down list that displays all the existing API versions. You can create a new version of an API and retain applications that are associated with older versions of the API. When an API is updated, it retains the Expose to consumers
settings, the existing scope definitions, the configured policies, and the REST-enabled path configurations for SOAP API.
When you create a new version, the newer version is assigned to the teams of the older version by default. You can later change the teams, if required.
Creating New API Version
You must have the API Gateway’s manage APIs functional privilege assigned to perform this task.
You can create a new version of an API from the latest version available for the API. For example, if the existing version is 1.1 for an API, you can create a version 1.2. If you want to create a version 1.3, you can only create it from the latest version 1.2 and not from 1.1. However, you can delete the intermediate versions. Additionally, even though the owner of the older API version is a different provider, when you create a new version of the API, you are the owner of the newly created version of the API. The new API version is in inactive state, irrespective of the state of the API from which it was versioned.
To create a new version
Click APIs in the title navigation bar.
Select the required API from the list of APIs.
Click and select Create new version.
In the Version field, type the new version for the API.
Clear the Retain applications checkbox if you do not want to retain applications that are associated with older versions of the API.
Click Create.
The Version drop-down lists the newly created API version in latest to older order in the API details page. The corresponding API details page is displayed when you select any particular version.
Deleting APIs
Deleting a Single APIDeleting Multiple APIs in a Single OperationDeleting an API permanently removes the API from API Gateway.
When deleting an API, keep the following points in mind:
You cannot delete an API if it is in active state. You have to deactivate the API before deleting it.
You must have the Manage APIs functional privilege.
When you delete an API, performance metrics and event information of the API are also deleted.
Deleting a Single API
Pre-requisites:
You must have the Manage APIs functional privilege assigned to perform this task.
You delete an API to remove it from API Gateway permanently.
To delete an API
Click APIs in the title navigation bar.
A list of all APIs appears.Click the Delete icon for the API that you want to delete.
Select the Force delete option to delete an API forcefully.
API Gateway ignores any failures even if the API is used by other applications, and clears all data from the API Gateway database.Click Yes in the confirmation dialog.
The API is deleted forcefully.
Deleting Multiple APIs in a Single Operation
Pre-requisites:
You must have the Manage APIs functional privilege assigned to perform this task.
You can bulk delete APIs in API Gateway.
To delete multiple APIs in a single operation
Click APIs in the title navigation bar.
A list of all APIs appears.Select the APIs that you want to delete.
In the Menu icon, click Delete.
Select the Force delete option to delete APIs forcefully.
API Gateway ignores any failures even if the selected APIs are used by other applications, and clears all data from the API Gateway database.Click Yes in the confirmation dialog.
The APIs are deleted forcefully from API Gateway.Examine the Delete APIs report window and check for any errors that occurred during the deletion process.
The Delete APIs report window displays the following information:Parameter Description Name The name of the deleted API. Status The status of the deletion process. The available values are: - Success
- Failure
Description A descriptive information if the deletion fails or if a warning occurs. API Gateway writes these results to the Audit logs dashboard, so you can view them later.
Click Download the detailed report here to download the detailed report as an HTML file.
Example - Managing an API
No subtopics in thissection
This section explains everything you would want to know about an API and how to manage it with an example API phonestore
. You can model an API that serves to expose API data and functionality as a collection of resources. Each resource is accessible with unique Uniform Resource Identifiers (URLs). In your API, you expose a set of HTTP operations (methods) to perform on a specific resource and capture the request and response messages and status codes that are unique to the HTTP method and linked within the specific resource of the API.
The basic elements of an API are:
The API itself (for example,
phonestore
)Its resource (
phones
), available on the unique base URL (/phones
)The defined HTTP method (
GET
) for accessing the resource (phones
)Parameters for request representations (
412456
)A request generated for this method (
Request 123
)A response with the status code received for this request (
Response ABCD
)
The example API phonestore
that we consider here is defined to support an online phone store application. Assume, this sample phonestore
API currently has a database that defines the various brands of phones, features in the individual phones, and the inventory of each phone. This API is used as a sample to illustrate how to model URL patterns for resources, resource methods, HTTP headers and response codes, content types, and parameters for request representations to resources.
Base URL
The base URL of an API is constructed by the domain, port, and context mappings of the API. For example, if the server name is www.phonestore.com, port is 8080, and the API context is api. The full Base URL is:
http://www.phonestore.com:8080/api
API Parameters
Parameters defined at the higher API level are inherited by all Resources and Methods included in the individual resources.
API Resources
Resources are the basic components of an API. Examples of resources from an online phonestore
API include a phone, an order from a store, and a collection of customers. After you identify a service to expose as an API, you define the resources for the API.
For example, for the online phonestore
API, there are a number of ways to represent the data in the phone store database as an API. The verbs in the HTTP request maps to the operations that the database supports, such as select, create, update, delete.
Each resource has to be addressed by a unique URI. Along with the URI you’re going to expose for each resource, you also need to decide what can be done to each resource. The HTTP methods passed as part of an HTTP request header directs the API on what needs to be done with the addressed resource.
Resource URLs
An URL identifies the location of a specific resource.
For example, for the online phonestore API, the resources have the following URLs:
URL | Description |
---|---|
http://www.phonestore.com/api/phones |
Specifies the collection of phones contained in the online store. |
http://www.phonestore.com/api/phones/412456 |
Accesses a phone referenced by the product code 412456 . |
http://www.phonestore.com/api/phones/412456/reviews |
Specifies a set of reviews posted for a phone of code 412456 . |
http://www.phonestore.com/api/phones/412456/reviews/78 |
Accesses a specific review referenced by the unique ID 78 contained in the reviews of the phone of code 412456 . |
API Gateway supports the following patterns of resource URL: a collection of resources or a particular resource.
For example, in the online phonestore API, the patters are as follows:
Collection URL: http://phonestore.com/api/phones
.
Unique URL: http://phonestore.com/api/phones/412456/features
to retrieve a collection resource describing the key features of phone whose product code is 412456
.
Resource Parameters
Parameters defined at the higher Resource level are inherited by all Methods in the particular resource; it does not affect the API.
Resource Methods
Individual resources can define their capabilities using supported HTTP methods. To invoke an API, the client would call an HTTP operation on the URL associated with the API’s resource. For example, to retrieve the key feature information for phone whose product code is 412456
, the client would make a service call HTTP GET on the following URL:
http://www.phonestore.com/phones/412456/features
Supported HTTP Methods
API Gateway supports the standard HTTP methods for modeling APIs: GET, POST, PUT, DELETE, and PATCH.
The following table describes the semantics of HTTP methods for our sample Phone Store API:
Resource URI | HTTP Method | Description |
---|---|---|
/phones/orders |
GET | Asks for a representation of all of the orders. |
/phones/orders |
POST | Attempts to create a new order, returning the location (in the Location HTTP Header) of the newly created resource. |
/phones/orders/{order-id} |
GET | Asks for a representation of a specific Order resource. |
/phones/orders/{order-id} |
DELETE | Requests the deletion of a specified Order resource. |
/phones/orders/{order-id}/status |
GET | Asks for a representation of a specific Order’s current status. |
/phones/orders/{order-id}/paymentdetails |
GET | Asks for a representation of a specific Order’s payment details. |
/phones/orders/{order-id}/paymentdetails |
PUT | Updates a specific Order’s payment details |
Method Parameters
Parameters defined at the lower method level apply only to that particular method; it does not affect either the API or the resource.
API Parameters
Parameters specify additional information to a request. You use parameters as part of the URL or in the headers or as components of a message body.
Parameter Levels
A parameter can be set at different levels of an API. When you document a REST API in API Gateway, you define parameters at the API level, Resource level, or Method level to address the following scenarios:
If you have the parameter applicable to all resources in the API, then you define this parameter at the API level. This indirectly implies that the parameter is propagated to all resources and methods under the particular API.
If you have the parameter applicable to all methods in the API, then you define this parameter at the resource level. This indirectly implies that the parameter is propagated to all methods under the particular resource.
If you have the parameter applicable only to a method in the API, then you define this parameter at the method level.
API-level Parameters
Setting parameters at the API level enables the automatic assignment of the parameters to all resources and methods included in the API. Any parameter value you specify at the higher API level overrides the parameter value you set at the lower resource level or the lower method level if the parameter names are the same.
For example, if you have a header parameter called API Key that is used for consuming an API.
x-Gateway-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a
This parameter is specific to the entire API and to the individual components, that is resources and methods, directly below the API. Such a parameter can be defined as a parameter at the API level.
At an API level, API Gateway allows you to define the following types of parameters:
Query-String parameter
Header parameter
Resource-level Parameters
Setting parameters at the resource level enables the automatic assignment of the parameters to all methods within the resource. Any parameter value you specify at the higher resource level overrides the parameter value you set at the lower method level if the parameter names are the same. In contrast, the lower resource level parameters do not affect the higher API level parameters.
Consider the sample phonestore API maintains a database of reviews about different phones. Here is a request to display information about a particular user review, 78 of the phone whose product code is 412456
.
GET /phones/412456/user_reviews/78
In the example, /user_reviews/78
parameter narrows the focus of a GET request to review /78
within a particular resource /412456
.
This parameter is specific to the particular resource phone whose product code is 412456
and to any individual methods that are directly below the particular resource. Such a parameter can be defined as a parameter at the resource level.
At a resource level, API Gateway allows you to define the following types of parameters:
Query-String parameter
Header parameter
Path parameter
Method-level Parameters
If you do not set parameters at the API level or resource level, you can set them at a method level. Parameters you set at the method level are used for the HTTP method execution. They are useful to restrict the response data returned for a HTTP request. Any parameter value you specify at the lower method level is overridden by the value set at higher API-level parameter or the higher resource-level parameter if the names are the same. In contrast, the lower method-level parameters do not affect the higher API-level or resource-level parameters.
For example, the phonestore API described might have a request to display information contributed by user Allen
in 2013
about a phone whose product code is 412456
.
GET /phones/412456/user_reviews/78?year=2013&name=Allen
In this example, year=2013
and name=Allen
narrow the focus of the GET request to entries that user Allen
added to user review 78
in 2013
.
At a method level, API Gateway allows you to define the following types of parameters:
Query-String parameter
Header parameter
Parameter Types
API Gateway supports three types of parameters in REST API: Query-String, Header, and Path.
Let’s have a look at different parameter types to see how they can be used for parameterizing the resources.
Query-String Parameters
Query-String parameters are appended to the URI after a ?
with name-value pairs. The name-value pairs sequence is separated by either a semicolon or an ampersand.
For instance, if the URL is http://phonestore.com/api/phones?itemID=itemIDValue
, the query parameter name is itemID
and value is the itemIDValue
. Query parameters are often used when filtering or paging through HTTP GET requests.
Now, consider the online phonestore API. A customer, when trying to fetch a collection of phones, might wish to add options, such as, android v4.3 OS
and 8MP
camera. The URI for this resource would look like:
/phones?features=androidosv4.3&cameraresolution=8MP
Header Parameters
Header parameters are HTTP headers. Headers often contain metadata information for the client, or server.
x-Gateway-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a
You can create custom headers, as required. As a best practice, Software AG recommends that you prefix the header name with x-
.
HTTP/1.1 defines the headers that can appear in a HTTP response in three sections of RFC 2616: 4.5, 6.2, and 7.1. Examine these codes to determine which are appropriate for the API.
Path Parameters
Path parameters are defined as part of the resource URI. For example, the URI can include phones/item
, where /item
is a path parameter that identifies the item in the collection of resource /phones
. Because path parameters are part of the URI, they are essential in identifying the request.
Now, consider the online phonestore API. A customer wishes to fetch details about a phone {phone-id}
whose product code is 412456
. The URI for this resource would look like:/phones/412456
- Append a path parameter variable within curly
{}
brackets. - Specify a path parameter variable such that it exactly matches the path parameter defined at the resource level.
Parameter Data Types
When you add a parameter to the API, you specify the parameter’s data type. The data type determines what kind of information the parameter can hold.
API Gateway supports the following data types for parameters:
Data Type | Description |
---|---|
String | Specifies a string of text. |
Date | Specifies a date stamp that represents a specific date. The date input parameters allow year, month, and day input. This data type only accepts date values in the format yyyy-mm-dd . |
Time | Specifies a timestamp that represents a specific time. The time input parameters allow hour and minute. This data type only accepts date values in the format hh:mm:ss . |
Date/Time | Specifies a timestamp that represents a specific date and/or time. The date/time input parameters allow year, month, and day input as well as hour and minute. Hour and minute default to 0. This data type only accepts date values in the format yyyy-mm-dd ; and time values in the format hh:mm:ss . |
Integer | Specifies an integer value for the data type. This is generally used as the default data type for integral values. |
Double | Specifies the double data type value. This is a double-precision 64-bit IEEE 754 floating point and is generally used as the default data type for decimal values. |
Boolean | Specifies a true or false value. |
Supported HTTP Status Codes
An API response returns a HTTP status code that indicates success or failure of the requested operation.
API Gateway allows you to specify HTTP codes for each method to help clients understand the response. While responses can contain an error code in XML or other format, clients can quickly and more easily understand an HTTP response status code. The HTTP specification defines several status codes that are typically understood by clients.
API Gateway includes a set of predefined content types that are classified in the following taxonomy categories:
Category | Description |
---|---|
1xx | Informational. |
2xx | Success. |
3xx | Redirection. Need further action. |
4xx | Client error. Correct the request data and retry. |
5xx | Server error. |
HTTP/1.1 defines all the legal status codes. Examine these codes to determine which are appropriate for your API.
Now, consider the online phonestore API. The following table describes the HTTP status codes that each of the URIs and HTTP methods combinations will respond:
Resource URI | Supported HTTP Methods | Supported HTTP Status Codes |
---|---|---|
/phones/orders |
GET | 200 (OK, Success) |
/phones/orders |
POST | 201 (Created) if the Order resource is successfully created, in addition to a Location header that contains the link to the newly created Order resource; 406 (Not Acceptable) if the format of the incoming data for the new resource is not valid |
/phones/orders/{order-id} |
GET | 200 (OK); 404 (Not Found) if Order Resource not found |
/phones/orders/{order-id} |
DELETE | 200 (OK); 404 (Not Found) if Order Resource not found |
/phones/orders/{order-id}/status |
GET | 200 (OK); 404 (Not Found) if Order Resource not found |
/phones/orders/{order-id}/paymentdetails |
GET | 200 (OK); 404 (Not Found) if Order Resource not found |
/phones/orders/{order-id}/paymentdetails |
PUT | 201 (Created); 406 (Not Acceptable) if there is a problem with the format of the incoming data on the new payment details; 404 (Not Found) if Order Resource not found |
Sample Requests and Responses
To illustrate the usage of an API, you provide a sample request and response messages. Consider the sample phonestore API that maintains a database of phones in different brands. The phonestore API might provide the following examples to illustrate its usage:
Sample 1 - Retrieve a list of phones
Client Request
GET /phones HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Connection: Keep-Alive
Server Response
HTTP/1.1 200 OK
Date: Mon, 29 August 11:53:27 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Mon, 18 July 2016 09:18:16 GMT
Content-Length: 356
Content-Type: text/xml
<phones>
<phone>
<name>Asha</name>
<brand>Nokia</brand>
<price currency="irs">11499</price>
<features>
<camera>
<back>3</back>
</camera>
<memory>
<storage scale="gb">8</storage>
<ram scale="gb">1</ram>
</memory>
<network>
<gsm>850/900/1800/1900 MHz</gsm>
</network>
</features>
</phone>
<phone>
<name>Nexus7</name>
<brand>Google</brand>
<price currency="irs">16499</price>
<features>
<camera>
<front>1.3</front>
<back>5</back>
</camera>
<memory>
<storage scale="gb">16</storage>
<ram scale="gb">2</ram>
</memory>
<network>
<gsm>850/900/1800/1900 MHz</gsm>
<HSPA>850/900/1900 MHz</HSPA>
</network>
</features>
</phone>
</phones>
Client Request
GET /phones/phone-4156 HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Connection: Keep-Alive
Server Response
POST /phones/phone HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Content-Length: 156
Connection: Keep-Alive
<phones>
<phone>
<name>iPhone5</name>
<brand>Apple</brand>
<price currency="irs">24500</price>
<features>
<camera>
<front>1.2</front>
<back>8</back>
</camera>
<memory>
<storage scale="gb">32</storage>
<ram scale="gb">2</ram>
</memory>
<network>
<gsm>850/900/1800/1900 MHz</gsm>
<HSPA>850/900/1900 MHz</HSPA>
</network>
</features>
<phone>
</phones>
Sample 3 - Create a phone
POST /phones/phone HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Content-Length: 156
Connection: Keep-Alive
<phones>
<phone>
<name>iPhone5</name>
<brand>Apple</brand>
<price currency="irs">24500</price>
<features>
<camera>
<front>1.2</front>
<back>8</back>
</camera>
<memory>
<storage scale="gb">32</storage>
<ram scale="gb">2</ram>
</memory>
<network>
<gsm>850/900/1800/1900 MHz</gsm>
<HSPA>850/900/1900 MHz</HSPA>
</network>
</features>
<phone>
</phones>
Server Response
HTTP/1.1 200 OK
Date: Mon, 29 August 11:53:27 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Wed, 18 June 2014 09:18:16 GMT
Content-Type: text/xml
Content-Length: 15
<id>2122</id>
CentraSite Provided APIs
No subtopics in thissection
When you want to perform governed API development with CentraSite and API Gateway, you can create an API in CentraSite defining the design-time aspects. The API can be deployed to the API Gateway. In such cases, you can also see that particular CentraSite destination is being configured in API Gateway. The API details for the CentraSite provided APIs are set as read-only. However, you can edit the run-time aspects such as scope and policies.
When you deploy
A REST API from CentraSite, you cannot modify the Basic information, Technical information, Resource and methods, and Components sections. The above mentioned sections are marked as read-only. However, you can modify the fields in the API Mocking and Documentation sections.
A SOAP API from CentraSite, you cannot modify the Basic information, Technical information, Resource and methods, and Components sections. The above mentioned sections are marked as read-only. However, you can modify the fields in the REST transformation, API Mocking, and Documentation sections.
An OData API from CentraSite, you cannot modify the Basic information and Technical information sections. The above mentioned sections are marked as read-only. However, you can modify the fields in the Documentation section.
For more information about Modifying API, see Modifying API Details.