APIC supports OpenAPI design, multiple security standards, has an extensive repository of Out-of-the-Box (OOTB) Policies, and supports various logic constructs. This really enables developers to develop advanced APIs.
It is practically impossible for a single book to cover every feature and function provided by APIC and all the use cases that it can solve; the concepts discussed in the following sections should make it easier for you to undertake API development with much more confidence. And for the preparation of that journey, you will learn about the following in this part of the chapter:
- OpenAPI design
- Creating a simple proxy API
- Testing APIs
- Variable usage
- Enhancing APIs by applying policies
- Error handling
Let’s explore each topic in detail.
What is an OpenAPI design?
The OpenAPI Specification (OAS) is the grammar to the language of the API. Grammar is a sign of a language’s maturity and advancement. Mature APIs use OAS grammar rules and syntaxes to describe themselves. Any API written following these grammar rules is called an open API.
In other words, an OpenAPI document is a document (or set of documents) that defines or describes an API using OAS. OAS specifies a standard format for describing a REST API interface in a standard, vendor-neutral, and language-neutral way. The OAS standard is necessary because it helps in the API economy’s growth through increased API consumers’ participation (after all, standards-driven communication leads to more participants).
OAS is the most widely adopted specification today when it comes to describing RESTful APIs. It is worthwhile mentioning that OAS is not the only specification out there. Some notable mentions are RESTful Service Description Language (RAML – https://raml.org/) and API Blueprint (https://apiblueprint.org/).
An API definition (or an OpenAPI document) is written in a file that can either be a JSON or YAML formatted document. The main sections of an OpenAPI document from an OAS 3.0 perspective are Info, Servers, Security (Scheme and Enforcement/Security), Paths, Operations, Parameters, and Responses.
Security Definition and Security Enforcement:
Security Scheme: This is where you can specify the security implementation details such as authentication URLs, OAuth settings, and API keys’ header names. It is worth highlighting that creating a scheme does not enforce that scheme on an API consumer. You can define multiple schemes in your API Proxy but have only one of those schemes enforced upon that proxy’s consumers. The enforcement of the scheme is done by Security Enforcement.
Security Enforcement or simply called Security: This is where you enforce the Security Scheme on the API consumer.
At the time of writing this chapter (September 2021), OAS 3.1.0 is the latest candidate release. These are the following things that you should be aware of:
- APIC 10.x supports OAS 3.0 with certain limitations on both the user interface (Designer and API Manager) and DataPower API Gateway. Refer to IBM documentation for limitations: https://www.ibm.com/docs/en/api-connect/10.0.1.x?topic=definition-openapi-30-support-in-api-connect
- OAS 3.0 is not supported by DataPower Gateway (v5 compatible). OAS 3.0 API support is provided by the DataPower API Gateway only.
- APIC has extended the OAS and has added some of its own message processing policies to support complex message processing.
Since APIC supports OAS, any API definitions you build using OAS can be imported directly into APIC. You can view the OAS design of your API by clicking the Source icon on the Design tab. Refer to Figure 4.8:
Figure 4.8 – OpenAPI Source icon
You can update the source code within the source view or use the more user-friendly form view.
Note
There are two important distinctions to be made here:
API Proxy: An API proxy, in general, concerns itself with the implementation of an API definition in an API Management tool such as APIC. Though it is certainly possible to write an API proxy completely within APIC, without it having to connect to a backend service provider, you would typically implement an API proxy that proxies a backend service.
API: An API will mostly be related to the implementation of the service definition by a backend service provider, outside of the API management tool.
It is certainly possible for an API to deviate from the API definition that is proxied by an API Proxy. And that is where various Policies and logic constructs of APIC come into play. Policies and Logic constructs map the API definition of an API Proxy to the definition provided by the actual API.
You will now begin the process of creating an API Proxy using APIC.