Overview
API Gateway provides the ability to view, create, and manage APIs, and publish the APIs to API Portal for consumption. API administrators and users with the appropriate functional privileges can use API Gateway to create and manage APIs, and publish the APIs to API 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, resources that are accessible using URIs, and resources that are represented by media types. This framework provides RESTful 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.
![*](chapterTOC_bullet.png)
The RAML specification is a YAML-based language for the definition of HTTP-based APIs that embody most or all of the principles of REST. The RAML specification provides all the information necessary to describe RESTful or practically-RESTful APIs.
![*](chapterTOC_bullet.png)
The Swagger 2.0 specification defines a standard, language-agnostic interface to RESTful APIs. The Swagger specification provides a complete framework implementation for describing, producing, consuming, and visualizing RESTful APIs.
![*](chapterTOC_bullet.png)
The OpenAPI 3.0 Specification (OAS) has a much more modular and reusable approach for describing and documenting RESTful APIs. OAS enables more power and versatility when it comes to describing the request and response messages, as well as providing details on the common components like the schemas and security definitions
Simple Object Access Protocol (SOAP) defines a communication method for XML-based message exchange over different transport protocols, such as HTTP and 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.
WebSocket protocol defines two-way (full-duplex ) communications between the client and the server, over a single Transmission Control Protocol (TCP) socket. The WebSocket protocol facilitates real-time data transfer from and to the server. This framework provides WebSocket APIs (with a RESTful interface) based on W3C standards.
Asynchronous APIs
The synchronous and asynchronous nature of an API is a function of the time frame from the request to the return of data. In the case of synchronous APIs, the expectation is that there would be an immediate return of data, read from a database, from the internet, from the disk, or any other I/O source of data. You would use synchronous APIs where data or service availability, resources and connectivity are high and low latency is a requirement. The application requests data and waits for it until a value is returned.
In the case of asynchronous APIs, the availability of a resource, service or data store may not be immediate. An asynchronous API returns a response acknowledging the receipt of the request and it continues with the processing of the data till it is done, and returns a response to the client only when the processing of the data is completed. You would use asynchronous APIs where data or service availability and connectivity are low or over-saturated with demand. These APIs may use the callback functionality to send the callback request to the requester when the requested resource is ready.
Few APIs may take a lot of time to complete their processes, for example, processes such as purging or archiving of events, and bulk processing operations. In such a scenario, a time-out may occur for these API invocations as it takes longer time in the synchronous way where there is a wait period for the return of the data.
Example: Let us consider an example of purging logs.
In the synchronous way, the client application sends a request to the native API to purge a set of logs with a filter specified. The native API in turn sends out a response with an acceptance along with a Job ID. The client uses this job ID to send out requests to the native API to check whether the job is completed. In this case the client may have to send out multiple requests to check whether the job is done.
To avoid the hassle of multiple calls to the native API and waiting for the job to get done, you can implement an API to behave asynchronously to avoid multiple checks. You can implement a REST API with a callback option that can be used to call back the requestor when the job is done. In this scenario, when the client application sends out a request to the native API to purge a set of logs with a filter specified, the native API in turn sends out a response with an acknowledgement of having received the request and makes a note of the callback request URL that it receives in the request. Now, the client does not have to send out multiple requests to the native API to check whether the job is done. Instead once the job is done, the native API uses the callback URL details to send out a response to the requestor regarding the status of the job being done.
API Gateway provides asynchronous form of API support for REST APIs.
API Gateway provides the capability of defining the callback component with the supported method parameters while creating a REST API. For details on creating an API with the callback definition, see
Creating a REST API. In addition you can configure
API Gateway to accept the requests from the client that contain the callback request URL and wrap it with its own URL before routing it to the native API. This lets
API Gateway track the requests that the client sends to the native API and the responses that are sent by the native API to the client. For details on how to configure the callback processor settings to enable processing the callback requests, see
Configuring API Callback Processor Settings. When a client sends a request with the callback request URL to the native API, API Gateway identifies the callback request URL in the incoming request, depending on the configured callback processor settings wraps the request coming from the client with its own URL and routes it to the native API. When the requested resource is ready, the native API sends a request to the callback request URL it has received in the request it has received from API Gateway. API Gateway then routes this request to the client. You can configure API Gateway to enforce any of the response processing policies that suits your needs on the immediate responses as well as the callback requests being sent from the native API to the client.
The callback requests-related event types can be distinguished by a new field with the value set to true and displayed in the dashboard in the transaction event type. For a normal request this field is set as false. The following are the field names that are displayed for various configured destinations:
![*](chapterTOC_bullet.png)
For API Gateway destination the field name is
callbackRequest, which is set to true.
![*](chapterTOC_bullet.png)
For Elasticsearch destination the field name is
isCallbackRequest, which is set to true.
![*](chapterTOC_bullet.png)
For all other destinations, API Portal, Audit Log, CentraSite, Email, JDBC, and Local log, the field name is
isCallbackRequest, which is wrapped under the
customFields column.
You can create and manage APIs from the Manage APIs page. The page lists all the APIs, their description, and version number. You can create an API, delete an API, view API details, activate or deactivate an API, publish or unpublish an API, and view API analytics from this page.
You can create an API in one of the following ways:
![*](chapterTOC_bullet.png)
Create an API by importing a definition for an existing API (for example, in Swagger or RAML format) using an API importer
![*](chapterTOC_bullet.png)
Create an API from scratch and set its attributes manually
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.
The table lists the API types and the file formats required as input to create an API using an importer.
API type | File format |
REST | RESTful API Modeling Language (RAML) Yet Another Markup Language (YAML) JavaScript Object Notation (JSON) OpenAPI Specification (OAS) |
SOAP | Web Service Definition Language (WSDL) |
OData | Entity Data Model (EDMX) |