Defining and Managing APIs
APIs 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 and resources. These operations and resources are accessible using URIs and are represented by media types. The RESTful framework provides REST APIs based on the REST architecture. There are multiple specification formats for REST APIs. In API Gateway, you can create a REST API using RESTful API Modeling Language (RAML), Swagger 2.0, or OpenAPI 3.0 specifications.
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). The SOAP 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 Defines two-way (full duplex) communication 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. The WebSocket framework provides WebSocket APIs with a RESTful interface based on W3C standards.
GraphQL Defines a query language designed to build client applications by providing a flexible syntax and 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 The client application requests data and waits until it receives a response to proceed with other processes. The expectation is an immediate response. | | 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 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 definition, see
Creating a REST API from Scratch.
Creating APIs
You can create and manage APIs from the Manage APIs page in API Gateway UI. The page lists all your 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.
Note:
Do not provide values starting with a dot (.), in any of the fields in API Gateway UI as Elasticsearch does not support saving those values.
