[Article] API Management Best Practices with WSO2 API Manager

  • By Chamin Dias
  • 20 Mar, 2017

When it comes to the API management arena, there are many best practices that need to be followed in order to create a productive and useful API management environment. WSO2 API Manager has been designed in a way that users (both API developers and consumers) can adhere to these best practices. This guarantees total customer satisfaction and optimized results when managing APIs in various business domains. Let us have a look at some of the major best practices related to API management and how WSO2 API Manager can be used to adhere to those practices.

API-first design approach

API developers must have their API design as accurate as possible because once the API is published, it is not recommended to make changes. (API acts as a contract between the service providers and consumers, therefore API design should be well defined). If there is a need to update the contract (i.e. - API), we need to create a new version instead of editing an existing API.

A high-quality API management solution should provide a mechanism to design the API by considering both technical and business aspects. Technical aspects are important for API developers. On the other hand, API consumers and service providers are interested in business aspects. WSO2 API Manager has the capability of facilitating both parties.

When creating an API, API developers can use the API Publisher web interface of WSO2 API Manager as it supports all the needs of API developers and publishers when it comes to creating and publishing APIs. They can decide the visibility and subscription availability for the API in a multi-tenant environment. Usually, in organizations, there are multiple business entities (i.e. - tenants) where API visibility should be controlled across tenants, according to the requirements of the business domain. Refer to the article on multi-tenant API management with WSO2 API Manager, for a panoramic view of this.

WSO2 API Manager also has an integrated Swagger UI. This is useful when it comes to designing and developing APIs. More information about the Swagger UI can be found in the official documentation as well.

Moving further, we can observe that WSO2 API Publisher has the capability to include API resources, manage different endpoints (for production and sandbox environments), create extensions using user defined handlers and enable response caching to enhance performance.

Figure 1: Define resources for an API

Figure 2: Including endpoints for an API

All the above facts needed to be considered by API creators/publishers when they need to expose an API to the community. They can use WSO2 API Manager to make things easier while adhering to API design best practices.

API lifecycle management

An API has a lifecycle. It is an agile process for managing the life of an API. At each lifecycle stage, the API can behave in a different manner. This enables API developers to improve their APIs and refine the implementation before deploying the API in a production environment. At the same time, API lifecycle is useful for API consumers as well. API consumers can take decisions for their API consumption from time to time, at each API lifecycle stage. For example, if an API is at “Deprecated” stage, consumers are given a chance a to consume that API until they upgrade to the newer version.

Let us have a look at the API lifecycle in WSO2 API Manager.

In API Publisher web interface, we can find a graphical representation of the complete API lifecycle.

Figure 3: Pictorial representation of API lifecycle

Accordingly, we can identify that there are several stages.

  • Created state - This is the starting stage of the API. The API developer has started creating an API, but it is not visible at API Store web interface.
  • Prototyped state - At this stage, the API can be used for the purpose of early promotion and testing. Subscribers can try out without a subscription or monetization, and provide feedback to improve the service. This helps API developers to refine the API and make sure it is production ready in a way that it is beneficial to most of the users.
  • Published state - API is deployed as a production ready service. Consumers must have a valid subscription to the API if they are interested in using the service.
  • Blocked state - If there is a need to block access to an API (for existing consumers), API developers can change the lifecycle to “Blocked”. This might be useful when there are security issues or service violations. Once the issue is fixed, API developer can re-publish the API. Also, it is possible to deprecate the API if needed.
  • Deprecated state - With continuous improvements, some APIs need to be updated with latest practices. In those kinds of cases, an API can be “Deprecated” and API developers can develop a new version based on the updated technology. However, to minimize the impact on existing consumers, API publishers can make allow existing subscribers to use the API until they upgrade to the newer version. No new subscriptions are allowed for a deprecated API.
  • Retired state - This is the final stage of an API. No more new subscriptions for the API and existing subscriptions are also removed. The API is unpublished from the API gateway and deleted from the store.

Based on the above information, it is clear that WSO2 API Manager can be used to manage the complete API lifecycle with ease. This is beneficial to both API developers (publishers) and API consumers.

Manage services through API versioning

Practically it is impossible to get the API design perfectly for the first time itself. Once the API is being used, we get to know about it properly. At that time, there may be requirements to have modifications.

However, it is not recommended to modify a published API which already has consumers. The best practice is to create a new version of the same API with the update/change. An API can be considered as a contract between service providers and consumers. Therefore editing an API with active subscriptions will sometimes violate business agreements. That is why it is recommended to create a new version of the same API (with the change) if API publishers need to update an existing API with active subscriptions.

Time to time, there might be requirements to update existing contracts and policies between service providers and API consumers. Normally, if an API is updated (API's behavior, authentication mechanism, resources, throttling tiers, target audiences etc), it is first deployed as a prototype. This option is useful for the API consumers to try the new version in advance. In this way, API publishers can keep the older version along with the updated version. After a period of time during which the new version is used in parallel with the older versions, the prototyped API can be published and its older versions can be deprecated.

Figure 4: Specify what is to be done at the time of publishing the updated API

Administrators can configure WSO2 API Manager to show all versions of an API or they can show only the latest version in API Store.

WSO2 API Manager supports all these business requirements. Therefore it can be used to handle any API versioning use case with ease.

Associating SLAs

In the API management space, it is very important to include well structured SLAs (service level agreements). It should provide a mechanism to associate SLAs for APIs. WSO2 API Manager allows you to specify different types of rate limiting policies for APIs, applications, and users.

Benefits of throttling include making an API, application or a resource available to a consumer at different levels of service (usually for monetization purpose based on SLAs), protecting APIs from common types of security attacks and regulating traffic according to infrastructure availability.

With this throttling feature, it is possible to specify the limit your back-end service can handle, enforce throttling to an API, apply fair usage policy for an application and apply multi-layer throttling. In addition to that, WSO2 API Manager facilitates to define rules based on IP address/address range, HTTP request headers, claims, and query parameters.

Figure 5: Adding an advanced throttling policy

More information about the new throttling engine can be found in one of the library articles. Also, there is another article to describe the architectural details of that as well.

Accordingly, it is clear that WSO2 API Manager is capable of associating any complex SLAs with APIs.

Promote, advertise and socialize APIs

In today’s world, there are many social media platforms with billions of user accounts. Sharing APIs in these social media and websites will definitely help to boost the number of API consumers. Therefore, socializing APIs is important to generate more revenue to the service providers who are exposing their services via APIs.

WSO2 API Manager is designed to facilitate the aforementioned requirements. There are ways to socialize APIs using WSO2 API Manager, with ease.

Mainly these community features can be found in API Store because it is where the APIs are presented to the outside world. In API Store, there is a facility to search APIs based on different attributes. API name, API provider, API version, API documentation, and API status are some of the supported search criteria. This allows users to search for interested APIs in a massive production environment with many APIs, using several dimensions.

Rating and commenting give useful insight to potential new API consumers. It helps to get an idea of the user feedback and evaluate the API before subscribing.

Figure 6: Rating an API

In WSO2 API Store, there is a section for sharing APIs in social media. It can be used to share the API on social media or to Email. This helps to grow the API consumer community.

Figure 7: Social media sharing and Email feature in API Store

Furthermore, it is possible to embed an API widget. It will facilitate to share the API on websites or web pages.

In WSO2 API Store, consumers can participate in the forum to discuss their ideas about the APIs. This helps to build more user interaction and share insight about the API.

Figure 8: Discussion forum in WSO2 API Store

Aforementioned features in WSO2 API Manager enables to socialize and promote APIs. Eventually it will be helpful to grow the number of API consumers.

Securing APIs

Nowadays, security is one of the main concerns in any IT application. This has the same importance for API Management as well. With WSO2 API Manager, API publishers need not worry about the security of their APIs, because WSO2 API Manager has inbuilt support for API security mainly based on OAuth 2.0. API consumers should obtain an access token to consume the subscribed APIs, which is handled by the key manager component of WSO2 API Manager. WSO2 API Manager supports the four most common authorization grant types and you can also define additional types. The grant types are used to authorize access to protected resources in different ways.

  • Authorization Code Grant - In this grant type, client directs the resource owner to an authorization server. This server works as an intermediate node between client and resource owner and enables to issues an authorization code, authenticate the resource owner and obtain authorization.
  • NTLM Grant - This grant type is for Windows operating system. If you have the API Manager server in a Windows environment, then you can use NTLM grant for authorization purposes.
  • Password Grant - Resource owner's username and password is needed (as an authorization grant) in this grant type. This method is suitable in cases where the resource owner has a trust relationship with the client and in situations where client can obtain the resource owner’s credentials.
  • SAML Extension Grant - In some applications it is required to consume OAuth protected resources through APIs (environments with SAML2 based SSO infrastructures). In these scenarios, the applications prefer to use the existing trust relationship (with the identity provider). WSO2 API Manager can facilitate the aforementioned requirement by exchanging the SAML2.0 token to an OAuth token with the authorization server.

Figure 9: Generating an access token to consume an API

It is possible to extend the key manager in WSO2 API Manager using WSO2 Identity server as the key manager and configuring a third party key manager can be found in the official documentation. Authenticating via Facebook and Google can also be done. Moreover, it is possible to achieve fine-grained resource usage and access control related to API management, with WSO2 API manager. A scope enables fine-grained access control for each resource of the API based on specific consumer roles. This way, when a consumer invokes the API with an access token, it will ensure that only the allowed resources can be accessed by the consumer. Refer to the article on scope management to get the complete picture and examples about this.

According to above point, it is clear that API security can be easily handled with WSO2 API Manager.

API rate limiting

API rate limiting and managing API traffic is important in real world deployments. This is somewhat aligned with the scalability.

The traffic manager of WSO2 API Manager is responsible for regulating API traffic, making APIs and applications available to consumers at different service levels, and securing APIs against security attacks. It helps users to regulate API traffic as well. The traffic manager has a throttling engine to process throttling policies in real-time, including rate limiting of API requests, which makes it fully functional. There are articles on scalable traffic manager deployment patterns with more information.

The API gateway plays a role of a proxy that intercepts API requests and applies policies such as throttling and security checks. Gathering API usage statistics is another function of gateway. The request is validated (i.e - security and throttling validations), and it will pass Web service calls to the actual back end.

Figure 10: API Manager deployment diagram with traffic manager and gateway

Since WSO2 API Manager is a scalable API management solution, managing API traffic and rate limiting is not much hard. API gateway and API traffic manager collectively contribute to managing API traffic and taking throttling decisions.

Monitor and assess API usage

Monitoring API usage and other related facts is an important task in a production environment based on APIs. It will help service providers to offer a better customer experience while exposing their services in the most optimal manner. Hence, a productive API management solution should be able to provide facilities related to gaining knowledge from API statistics via real-time analysis and batch analysis.

WSO2 API Manager supports not only batch analytics, but also real-time analytics. Mainly the batch analysis contains API Publisher related statistics and API Store related statistics. Graphs and tables related to published APIs over time, API usage, API last access times, usage by resource path, usage by destination are some of the statistics related to API Publisher. Top users, resource usage, faulty invocations are related to analytics in API Store. In addition to that, there is real-time analytics model in admin portal as well. There are two major sections with respect to real-time analysis. These are alert types and log analyzers. More details on configuring analytics is included in the official documentation. WSO2 API Manager allows you to monetize APIs based on the usage, by specifying a given billing plan for tiers.

Moving further, analytical models in WSO2 API Manager can be used to generate insight to make effective decisions related to API Management. We have explained those scenarios in a previous article as well.


In real-world production environments, there are different deployment patterns. There might be situations to expand the size of the deployment. In those kinds of scenarios, the API Management solution should be scalable (the capacity to be changed in size or scale).

WSO2 API Manager provides a scalable and flexible deployment option with complete control over infrastructure and management of APIs. It overcomes the challenges of building cost-effective, future-proof infrastructure that satisfies the user's and the organization's budgets. WSO2 API Manager can be mainly deployed in a single server or in a distributed environment.

In a single server deployment, a single API manager instance runs with all components (with API gateway, key manager, store, traffic manager and publisher all in one). This pattern is for simple deployments. We can use this for demonstration purposes and simple deployments with minimum load. If the load is high and if we need high availability, then it is recommended scale up the deployment. This is where the full distributed server deployment comes into play.

Figure 11: Single server deployment

In distributed deployment, we deploy the components (API gateway, key manager, store, traffic manager and publisher) in different servers. This is one of the most common deployment patterns. In this way, there are some advantages. Since each component runs on a dedicated server, we can assign resources and fine-tune nodes according to the requirements of components (e.g. if its gateway, we can tune gateway-related configurations, such and Synapse worker threads, gateway time-out, etc.).

Figure 12: Distributed deployment

More details on scalable deployment patterns can be found in this article as well.

With WSO2 API Manager, scaling a deployment is not a problem at all.


WSO2 API manager supports all key API Management best practices. This article focused on how API Management best practices can be followed using WSO2 API Manager. Since WSO2 API Manager is a complete, enterprise-ready solution for managing APIs across the complete API lifecycle, organizations can use it to manage APIs in any kind of complex production environment, while adhering to API Management best practices.

Applies to

  • Version 2.0 and above

About Author

  • Chamin Dias
  • Senior Software Engineer
  • WSO2