Key concepts

This topic introduces the key concepts and terminology in AMPLIFY API Management in detail.

API provider

The API provider is the enterprise deploying Axway AMPLIFY API Management to expose APIs to API consumers, like a credit card company providing payment services to various customers.

The API provider includes the following user roles:

  • API administrator: An API administrator has the overall responsibility for managing the consumption of APIs by API consumers. API administrator registers, tests, and publishes APIs to API Catalog, manages API consumers and policies controlling their API use, and monitors overall API usage.
  • API developer: An API developer develops the back-end services and applications that expose APIs. The API developer provides the details of the APIs to the API administrator who registers and publishes them in API Catalog. If delegated API registration (optional) is configured, the API developer can directly register, test, and publish the APIs.
  • Policy developer: A policy developer uses Policy Studio to develop custom policies that can be applied to APIs. The policy developer can double as an API developer and use Policy Studio to develop new APIs from back-end services and applications that do not expose APIs.
  • API Gateway administrator: An API Gateway administrator is a system administrator responsible for monitoring the API Gateway and traffic flowing through it. API Gateway administrator manages settings and configuration deployments, and troubleshoots any issues in the API Gateway. For more details, see the API Gateway Administrator Guide.

API consumers

API consumers use the APIs that the API provider provides. API consumers can be organizations, end users, client application developers, or client applications. For example, the API consumers for a credit card company could be specific hotel and retail organizations that enable their customers to make payments by credit card.

The following diagram shows the API consumer organizations and user roles:

The API consumers can be grouped as follows:

  • Organization: An organization defines the logical grouping of API consumers. An organization can be either external, such as a business partner, or internal, like a business unit or project team, to the API provider. Organizations are named and have a trusted relationship with the API provider.
  • External and internal organizations can be included in the same deployment. With delegated organization administration, the organizations can manage the application developers and client applications in their own organization by themselves.
  • Organization administrator: An organization administrator performs the administrative tasks that the API provider chooses to delegate to the organization. The organization administrator can use API Portal to manage client application developers within the organization, register new developers, and manage the credentials and monitor the API usage of all client applications in the organization.
  • Community organization: A community organization provides an optional, built-in organization of anonymous, untrusted API consumers not explicitly tied to any trusted organization. The community organization provides a mechanism to recruit external client application developers to browse APIs and to build client applications with minimal oversight and approval.
  • API consumers in the community organization can be associated with a named organization and become trusted. It is not recommended that production-level client applications run in the community organization. Instead, these API consumers must move to a trusted organization before the client application is deployed in production. Delegated organization administration is not supported for the community organization, and there is no organization administrator.
  • Client application developer: A client application developer develops and tests client applications (mobile and web) that use the APIs the API provider provides. The client application developer is a member of an organization and uses API Portal to browse API documentation, try APIs, manage client application credentials, and monitor API usage.
  • Client application: A client application consumes and invokes the APIs. The client application can be a mobile application, a web application, or a system-level application. The client application is associated with an organization.

API management

API management enables the API provider to publish REST APIs and SOAP web services to consumers, and to manage how these consumers use the APIs.

The following diagram shows the high-level API management architecture:

Diagram illustarting the API management architecture

This architecture includes the following capabilities:

  • API Catalog and lifecycle management: API administrators and API developers can register and manage the lifecycle of APIs. API Catalog lists published APIs that are available to API consumers.
  • API consumer management: API administrators can manage API consumers and apply policies to manage how API consumers use the APIs. AMPLIFY API Management solution includes partner-based management of API consumers. Delegated partner administration enables partner organizations to manage their own API consumers, making it easier for you to manage large partners or a large number of partners.
  • Policy management and enforcement: Provides built-in authentication, authorization, and quota management policies. These built-in policies can be extended with custom policies specific to the API provider.
  • Self-service API consumption: Application developers creating client applications that will use the APIs can consume the APIs as self-service. Application developers can self-register, browse API documentation, try APIs to understand their behavior, monitor their use of APIs, and find support on the APIs from blogs and discussion forums in API Portal.
  • Governance alerts: You can configure alerts generated for governance events associated with APIs, API consumers, policies, or runtime events. These alerts trigger custom policies to take the appropriate action, such as notifying an external notification system. The following are examples when you could use a governance alert:
    • When an API is deprecated and API consumers must be notified
    • When a new client application developer is registered and needs API administrator approval
    • A client application reaches its API quota

API development

API proxying assumes that the back-end service exposes REST APIs or SOAP web services that can be registered and proxied for API consumers to use. For more details, see API proxying. With AMPLIFY API Management, you can develop REST APIs from non-REST API back-end services using graphical policies.

The following diagram shows the API development architecture:

Diagram illustarting API development architecture

Note   It is recommended that policy-based APIs are deployed on separate API Gateway that is behind the internal firewall. In addition, the sandbox API and production API environments have separate API Gateways running the sandbox and production policy-developed APIs.

You can define the REST API and the policy to integrate the REST API with the back-end services in Policy Studio. You can then proxy the REST API and make it available to API consumers just like any other API. If you want to expose a REST API proxy for a back-end service that does not offer a native REST API, you must first develop a REST API for the back-end service. You can then proxy the newly developed REST API.

For example, in the SOAP-to-REST use case, an existing SOAP web service must be exposed as a new REST API. You design the REST API and integrate it with the SOAP web service. You proxy the REST API and make it available to API consumers. In addition, you could orchestrate multiple calls to the REST API to integrate it with multiple back-end services.

This way, there is a single consistent approach for registering APIs, proxying the APIs, and managing how APIs are consumed in API Manager regardless of the back-end API implementation (a native API or developed from a non-REST back-end API).

The lifecycle of policy-developed APIs is different to the lifecycle of the custom policies that are deployed on the same API Gateway that is running API Manager.

API proxying

AMPLIFY API Management enables you to proxy REST APIs and SOAP web services and apply policies to them to manage the consumption by API consumers. API consumers invoke the proxied APIs, and after the policies are applied, the request is routed to the back-end REST API or SOAP web service implementation.

API proxying includes the following approaches:

  • Proxy API without modifications:The API provider proxies the API as is, without any modifications. The proxied API exposed to API consumers is hosted on API Gateway, but it has the same API definition (methods, parameters, and documentation) as the original API.
  • Proxy API with modifications: The API provider proxies the API with modifications to make the proxied API more consumer-friendly to the API consumers. These modifications could involve any of the following:
    • Remove methods
    • Update the documentation
    • Rename method paths and parameters
  • Multiple proxied APIs: The API provider exposes the API as several different proxy APIs for different API consumers. For example, different API methods could be exposed to different API consumers, or different authentication policies could be used depending on the level of trust with the API consumer.
  • The proxied APIs could have differences in the following:
    • Methods exposed
    • Documentation
    • Method paths and parameters
    • Authentication and policies

For details on API proxying a back-end service without a native REST API, see API development.

API versioning

You can expose multiple versions of a single API to API consumers using AMPLIFY API Management. Each version of the API is managed as an independent API, with its own unique URL and its own API lifecycle.

For more details, see API provider.

Sandbox and production APIs

AMPLIFY API Management supports both sandbox and production APIs at runtime:

  • Sandbox APIs: API consumers can use the sandbox APIs to see what APIs are available for the API provider and to develop client applications against those APIs. Sandbox APIs route requests to sandbox services that the API provider has made available to support the development of client applications. Using API Portal, the application developer can browse the API documentation, try APIs to understand their behavior, manage client application credentials, and use the blogs and discussion forums to get more information. When the application developer represents also the end user when developing the client application.
  • Production APIs: Real end users using the client applications in production environment use the production APIs. Production APIs route requests to the production services of the API provider. Using API Portal, the application developer can manage client application credentials and monitor how the client application uses the APIs.

AMPLIFY API Management deploys sandbox and production APIs into separate environments. The different security and quality of service requirements between these environments keep sandbox and production API traffic separate.

The following diagram shows example sandbox and production API environments:

Diagram showing the comparison of the sandbox and production API enviroments

API consumer onboarding

API consumers are first onboarded into the sandbox API environment where they can learn about the available APIs and develop their client applications. Onboarding into the sandbox API means that you can have more relaxed rules concerning registering API consumers (including self-registration), and which APIs the consumers can access. The goal is to encourage consuming APIs, and this approach makes it easier for a wide community of API consumers. When an API consumer is ready to transition to production, the API consumer can be onboarded from the sandbox API environment to the production API environment.

Onboarding API consumers into the production API environment means you must have more governance processes in place. For example, to support the expected client application load for an external business partner, you may need to have financial and legal criteria, quotas, and SLA agreements all defined and set up.

Policy management and development

In AMPLIFY API Management, you can apply policies to APIs to manage how API consumers use the API.

The following diagram shows an overview of the policy management hierarchy:

Diagram showing the policy management hierarchy

AMPLIFY API Management provides a number of built-in policies that you can apply to APIs, for example:

  • Authentication mechanisms (such as, API keys or OAuth 2.0) for client applications
  • Authorization mechanisms for controlling both organizations' and client applications' access to APIs
  • Quotas to limit the API requests that client applications can make

The API developer or API administrator can apply these custom policies when registering an API.

In addition to the build-in policies, you can also configure custom policies, and apply them to the API request from the client application, the API response that is returned to the client application, or the routing to the back-end service. For example, you may have specific security policies that need to be applied to all API requests, or the identity of an end user of the client application may need to be authenticated and mapped to a different token.

The custom policies are developed independently of APIs to build a library of policies that can be applied to APIs. The policy developer uses Policy Studio to graphically develop. The developed policies can then be deployed in both the sandbox API and production API environments. The API developer or API administrator can apply these custom policies when registering an API.

The lifecycle of these custom policies is different to the lifecycle of APIs.

Related Links