Various features are related to creating, managing, and using APIs. Before creating or using an API, you should understand the key concepts surrounding Celigo's integrator.io API management. If you’re an API publisher creating an API, you should also learn more about the API Management console. If you’re an API consumer, you should also 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. API key plans offer only a basic level of security, acting more as a unique identifier than a security token since the API key can easily be found in the app code. 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 & 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.
Learn more about the Policy Studio’s features.
You can create and register an application as an API publisher (creating APIs) or an API consumer, though consumers most often create applications. Consumers who want to use APIs must register an application, allowing API publishers to control and regulate access to their 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)
Comments
Please sign in to leave a comment.