Key Concepts

Concept Description
API An API (Application Programming Interface) is the fundamental building block of WSO2 API Manager. It is an intermediate layer that acts as a communication protocol between a consumer and a service, simplifying the consumption of the service. In addition to hiding the underlying implementation details of a service, an API provides a secure, controlled, and a well-documented approach to accessing the exposed service.
API Format Open API Specification (OAS, a.k.a Swagger) format is the underneath representation of an API in WSO2 API Manager. A swagger definition can be used to import an API to the Publisher Portal. In addition, a user can view, edit, import, or download an API definition in OAS format via the API Publisher.
API Resource path and HTTP Methods An API is made up of one or more resources, each of which has a unique resource path (URI). An API Resource has a set of HTTP methods that operates on it. The supported HTTP methods are: GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS
API Lifecycle The stages that an API goes through from creation to retirement. APIs have their own lifecycle stages that are independent of the backend services they rely on. The lifecycle's states are CREATED, PROTOTYPED, PUBLISHED, DEPRECATED, and RETIRED. The life cycle of APIs is customized based on the needs of an organization.
Application The logical representation of a physical application such as a mobile app, web app, device, etc. For an application to use an API, the application should subscribe to the relevant APIs it intends to use. A subscription to an API happens over a selected business plan, which determines the usage quota the application gets. An application has a consumer-key and a consumer-secret, which acts as the credentials of the application.
API Product A combination of resources from one or more available APIs. An API product allows API product managers to mix and match resources from the available APIs. Similar to using an API, an application that intends to use an API product needs to subscribe to the APIs under a selected business plan. An application that subscribes to an API product gets access to all of its resources, which belongs to one or more APIs that are used to create the API product
Access Token Used in OAuth2.0 bearer token based authentication to allow a consumer to access an API. It is a string that is passed as an HTTP header of an API request. WSO2 API Manager supports JWT formatted self-contained access tokens and regular opaque access tokens.
API Visibility API visibility determines who can view the API on the developer portal. The available visibility levels are
  • Public - Visible to all users
  • Restricted by role - Visible only to the users under the creator's tenant domain who have the relevant roles attached
  • Visible to my domain - Visible to all users who are registered to the API creator's tenant domain. This applies only when there is more than 1 tenant in the system.
Rate Limits Rate limiting allows you to limit the number of permitted requests to an API within a given time window. Rate limiting can be useful to
  • Protect your APIs from common types of security attacks such as certain types of Denial of Service (DoS) attacks.
  • Regulate traffic according to infrastructure availability.
  • To apply request quotas for monetization purposes of APIs.
Workflows Allows controlling selected user actions on the API Publisher and the Developer portal. For example, enabling a human approval process to approve users signing up to the Developer Portal. Workflow plugins can be used creatively for other purposes as well, such as performing custom validations, compliance checks, etc. Its asynchronous nature developed on webhooks allows user actions to be put on hold in order to be completed later.
Message Mediation Policies Message mediation policies are used to enrich, transform, or modify a request or response message that is being routed via the API gateway. For example, when exposing an XML endpoint as JSON, message mediation policies may be used to convert the message format from XML to JSON and vice versa. These policies can also be used for composing services into APIs and for various other needs such as validations, conformance, etc.
Handler A handler allows a message to be processed before passing it to the routing logic of the API gateway. Handlers can be used for security validation, policy enforcement, pushing out events to third party systems, custom logging requirements, etc. A handler allows processing of both request and response messages.
Tags Tags allow API providers to categorize APIs that have similar attributes. When a tagged API gets published to the API developer portal, its tags appear as clickable links. API consumers can use the link to navigate to a category of interest. API consumers can also search APIs that match a particular tag on the developer portal.
Tenant A tenant in WSO2 API Manager is a logically isolated entity. A tenant can be mapped as an organizational unit, department, etc. Multi-tenancy enables such organizational units/departments to share the same API Manager deployment and the respective resources. But function individually with a personalized view/scope of the installation. Multi-tenancy is popularly used in SaaS offerings.
API Publisher Role An API publisher (API provider) is an API product manager. He/she manages a set of APIs and API products across the enterprise or business unit and controls the API lifecycle, subscriptions, and monetization aspects of an API or API product. The API Publisher can also analyze usage patterns for APIs and access all APIs statistics.
API Creator Role An API Creator is a person in a technical role who understands the technical aspects of the API (interfaces, documentation, versions, etc.) and uses the API Publisher portal for the design and development of APIs. APIs created by an API creator are managed (lifecycle managed and productized) by an API product manager.
API Subscriber Role A subscriber is a consumer of an API. He/she intends to develop one or more applications that consume APIs on the developer portal. A subscriber uses the API developer portal to discover APIs, read the documentation and forums, rate/comment on the APIs, subscribe, obtain keys, and finally use APIs from their applications.
Admin Role The admin user is responsible for managing the admin portal, which includes tasks such as approving workflows, managing rate limiting policies, configuring emails for bot detection/alerts, viewing the state and health of APIs, etc. In addition, the admin user is also capable of carrying out general administrative tasks such as managing users, roles, databases, security, etc.