Various features are related to creating, managing, and using APIs. Before building an API, you should understand the key concepts surrounding Celigo's API management. This article discusses the main concepts and features of the APIM console. If you’re an API publisher creating an API, you should also learn more about navigating the API Management console. If you’re an API consumer, you should learn more about using the Developer portal.
API plans determine how consumers will interact with your API. A plan provides a service and access layer on top of your APIs for consumer applications. You can create keyless plans with no authentication or tiered, authenticated plans. You can customize each plan with features like higher rate limits, additional endpoints, priority support, or advanced analytics. You can always change rate limits and quotas after you’ve created a plan.
There are four stages for plans:
-
Staging – The plan has been created but isn’t available for subscribers yet. You can make changes to the plan and preview it.
-
Published – The plan is active and available for subscribers.
-
Deprecated – The plan is available to users who have already subscribed. New users cannot subscribe to the plan.
-
Closed – The plan is closed and can’t be used by subscribers.
With tiered plans, you can specify the authentication methods (API key, OAuth, JWT, etc.), security features like IP whitelisting or encrypted communications, and versioning.
When documenting a plan, it’s important to include support resources and service level agreements (SLAs), billing and cost structures, upgrade and downgrade policies, and terms of service and acceptable use policies.
Important
All APIs published through integrator.io have an API key plan automatically generated.
The OAuth 2.0 authentication type checks access token validity during request processing using token introspection. If the access token is valid, the request is allowed to proceed. If not, the process stops and rejects the request. OAuth is an open standard that apps can use to provide client applications with secure delegated access. It works over HTTPS and authorizes devices, APIs, servers, and applications with access tokens rather than credentials. OAuth2 can only be enabled using Identity and Access Management software (IAM).
The JWT authentication type ensures that JWTs issued by third parties are valid. Only applications with approved JWTs can access APIs associated with a JWT plan.
JSON Web Tokens are an open method for representing claims securely between two parties. JWTs are digitally signed using RSA public/private key pairs. JWT plans allow you to verify the signature of the JWT and check if the JWT is still valid according to its expiry date.
JWT defines some registered claim names, including subject, issuer, audience, expiration time, and not-before time. In addition to these claims, the inbound JWT payload must include the client_id claim (see below) to establish a connection between the JWT and the APIM application subscription. The policy searches for a client ID in the payload as follows:
-
the
azpclaim -
the
audclaim -
the
client_idclaim
Use API key plans to enforce verification of API keys during request processing, allowing only apps with approved API keys to access your APIs. This plan type ensures that API keys are valid, are not revoked or expired, and are approved to consume the specific resources associated with your API. For a higher level of security, see OAuth 2.0 and JWT plans.
When configuring API key authentication, there are two main options:
-
Propagate API key to upstream API: Toggling this setting ensures the request to the backend API includes the API key header sent by the API consumer. This setting is useful for backend APIs with integrated API key authentication.
-
Additional selection rule: This setting allows you to use Expression Language (EL) to filter by contextual data (request headers, tokens, attributes, etc.) for plans of the same type. For example, if you have two API key plans, you can set different selection rules on each plan to determine which plan handles each request.
Typically, API keys are randomly generated for each subscription. However, integrator.io provides two other options for API key generation: custom API key and shared API key. Both settings can be enabled at the environment level by selecting Settings in the main sidebar and then selecting Settings again under the Portal group in the nested sidebar.
You can specify a custom API key for an API key plan. This is particularly useful when you want to migrate silently to APIM and have a pre-defined API key. The custom API key must be URL compliant and have more than 8 characters and less than 64 characters. The following characters are invalid:
-
#
-
%
-
@
-
/
-
;
-
=
-
|
-
~
-
,
-
<space>
When prompted, you can provide your custom API key or let APIM generate one by leaving the field empty. You can provide a custom API key when:
-
Creating a subscription
-
Accepting a subscription
-
Renewing a subscription
Keyless plans allow public access to the API and bypass any security mechanisms during the request process. By default, keyless plans offer no security and are most useful for quickly and easily exposing your API to external users and getting feedback. Due to the lack of a consumer identifier token (API key), keyless consumers are set as unknown applications in the API analytics section.
Your policies are customizable rules or logic the Gateway executes during an API transaction. Policies generally fall into security, transformation, performance, routing, or monitoring and testing categories. They are added to flows to enforce security, reliability, and proper data transfer. Examples of policies include traffic shaping, authentication/authorization, rate limiting, and dynamic routing. You can use dozens of policies; see the Policy Reference Guide for a comprehensive list.
The Policy Studio is a no-code tool for creating and managing your API. You can configure policies to determine how users will interact with the API, including what features of the API they can access and what governance policy configurations are enforced. The studio is laid out in a simple drag-and-drop format so that you can start quickly. To learn more about a specific policy, see the APIM Policy Reference Guide.
The Policy Studio allows you to design "flows" or policy enforcement sequences that protect, transform, or alter how APIs are consumed. It’s a no-code tool for creating and managing your API.
Important
-
An APIM flow relates to the different phases of creating, managing, publishing, and subscribing to an API in APIM. This is not the same as a Celigo integrator.io flow.
-
You do not have to create a flow to add a policy to the API. However, adding a flow allows you to better control what phases a policy is added to.
The Policy Studio's purpose and functionality are broken into the following sections:
-
Design – Manage all flows associated with your Gateway API
-
Configuration – Modify settings around flow execution
-
Properties – Define key-value pairs at the API level. These properties are read-only during the Gateway's execution of an API transaction.
-
Resources – Configure global resources to support your Gateway API's flows
You can create a flow in the Policy Studio and add one or more policies to the Request, Response, Publish, and/or Subscribe phases. To learn more about a specific policy, see the APIM Policy Reference Guide. When a policy is applied and how it is enforced depends on the phase:
-
Request phase – A policy is applied during the connection establishment. The Gateway enforces the policy at the time of the request before a client can access the API they are trying to call.
-
Response phase – A policy is applied to the response from the initial connection. The Gateway enforces the policy after the request is allowed, but before the response is returned to the client.
-
Publish phase – A policy is applied to messages sent to the endpoint. The Gateway enforces the policy when messages are published before clients can access the API they are trying to call.
-
Subscribe phase – A policy is applied to messages received by the entrypoint. The Gateway enforces the policy after messages are subscribed to, but before the response is returned to the client.
You can create multiple policies for a single flow, each with a different configuration and applied to a different API phase. Flows can also be associated with specific plans or as common flows at the API level.
To access your APIs, consumers must register an application and subscribe to a published API plan (unless the plan is keyless). Applications act on behalf of the user to request tokens, provide user identity information, and retrieve protected resources from remote services and APIs. Typical applications are web applications, native applications, or bash/job applications that access data.
When a new application is created, only the creator (Primary Owner) can see and manage the application. Most of the time, an application is shared through a developer application and will retrieve information such as API keys and API analytics.
By default, APIM includes three membership roles:
-
Primary owner – When an application is created, the primary owner is the application's creator. The primary owner can do all possible actions for an API.
-
Owner – The owner is the lightest version of the primary owner role. The owner can do all possible actions except delete the application.
-
User – A user is a person who can access the application in read-only mode and use the application to subscribe to an API.
A subscription is a successful contract between an API publisher and an API consumer. Subscriptions are created when an API consumer uses a registered application to create a subscription request to a published plan, and an API publisher either manually or automatically validates the subscription. APIs with keyless plans do not require the API consumer to create an application or submit a subscription request, as no authorization is required to access the backend API.
After creating an application, API consumers can subscribe to APIs (with published plans) in the Developer portal. The portal exposes published APIs so consumers can browse, request access, and use them. To access and interact with the APIs, consumers must have created an application and subscribed to a plan. In the API Manager, API publishers can approve subscriptions to secure access and identify consumers for monitoring and analytics.
In some cases, integrator.io will automatically generate your documentation. For MyAPI or other instances, you’ll have to generate your API specifications manually. Learn about best practices for creating documentation or learn more about using documentation provided by an API publisher.
|
|
|
Documentation in the APIM console (API publisher) vs Documentation in the Developer portal (API consumer)