Introduction
Although this is a reasonably technical document we try to make it as simple as possible (but not any simpler) and stay away from jargon as much as we can. When we use a term of product that might not be clear to the average reader we will explain it either directly or refer to the glossary of terms at the end of the article.
The structure of this article is as follows:
• A simple explanation what an API is and why you (might) need it;
• A one-liner (API Manager in 1 sentence) and an elevator pitch explaining what the API Manager is;
• More detailed explanation of the API Manager and its functions;
• Glossary of terms.
The purpose of an API
To make this article accessible for all readers, let’s quickly explain the concept of anApplication Programming Interface (API).
 |
|---|
| Image 1 Street in Princeton, what would the Zip Code |
| be? – CC Flickr – Patrick Nouhailler |
Writing good software among other things means writing modular software. Apart from the benefit of breaking down the complexity and being able to distribute development to a team of people it also enables reuse of parts of code that have a generic purpose.
A good example would be the lookup of a street name or city based on a zipcode.
The first reason it is a good example is that this type of functionality is used by many processes across your organization. Anyone who needs to send out mail or packages could use this, even customers entering their data on your website could benefit from it.
The second reason is that it makes no sense for your company to maintain your own zip code/street/city database, especially not when you have an international business and ship all over the world. Ideally you would like to get that information directly from the source who is maintaining it, e.g. a postal service or government body.
Let’s imagine the situation where a zip code and city is entered on a form:
The zip code is: 90210 and the city entered is: Ventura
Is this correct?
90210 is perhaps the most recognized zip code in the world and many will instantly see that the city is not correct, it’s Beverly Hills not the city of Ventura.
What you would do to verify or validate the entry is send a request to a City/State Lookup Web Tool to give you the corresponding city and state for a zip code.
 |
|---|
| Figure 1 Example City State lookup (sample code from the USPS API documentation) |
In the example in fig. 1 we even show the way the request is actually made using a request and the eXtensible Markup Language (XML) language. If you are unfamiliar with XML, don’t worry. What you need to know now is that XML clearly identifies the values using readable tags like and . Anything between those two is the actual value.
This is how you can use a service to check or validate a zip code. There is more to it, but for now this is what you need to know.
Note that this service is provided from outside your organization, not from inside. Increasingly organizations are connecting to the outside world, like business partners, Software as a Service (software that you use and pay per use), government or government bodies, clients and so on.
The number of APIs, both to internal systems as well as outside is increasing rapidly and to manage all those, that is where the WSO2 API Manager comes in.
API Manager in 1 sentence
The WSO2 API Manager takes care of all things that are related to the way programs talk or communicate with each other, just within your organization or connecting to the outside world.
Elevator pitch
The API Manager is the component that supports the whole API lifecycle, from cradle to grave. It furthermore monitors API usage and makes sure only those that are allowed to use them can use them. In total there are 5 separate components:
1. API Publisher: to make APIs available;
2. API Store: for offering APIs to your developers or consumers;
3. API Gateway: to route all your API calls (taking care of all the important nitty-gritty);
4. API Handlers: makes sure the API does want it needs to do and where it needs to do It;
5. API Key Manager: monitoring who wants to use your APIs and if they are allowed to.
WSO2 API Manager in detail
The purpose of the WSO2 API Manager is to manage all your Application Programming Interfaces (APIs). It is one of the core components of WSO2 and can be downloaded from the WSO2 Installation is quite easy, just follow the guidelines on the WSO2 website. A ‘How to install WSO2 components’ article will be available soon from the Yenlo website.
It offers the following functionality:
1. Create a Store of all Available APIs;
2. Publishing and Governing API Use;
3. Govern Complete API Lifecycle;
4. Monitor API Usage and Performance.
We will now look into more detail for each of these four categories.
Create a Store of all Available APIs
Apple is not only famous for its hardware like the iPhone and iPad but they have also made the whole concept of an app store a success. All the available applications in one place, easy for people to pick what they want. 
The API Manager uses the same type of graphical interface for the available API’s in your organization giving you the ability to browse and search for APIs (by provider, tags or name).
Developers can subscribe to APIs and manage these subscriptions (per application) and at different service tiers. There is a possibility to try out APIs directly from the storefront as well as browse documentation. There is even a possibility to rate APIs and comment on them.
For those who are managing the APIs there is a role based access, you determine who can add, delete or suspend public and private APIs (in cooperation with the WSO2 Identity Server). API keys can be provisioned and in cooperation with WSO2 Business Activity Monitoring component statistics can be viewed. Of course all of this is customizable to your needs, including i18n.
Publishing and Governing API Use
Another important part of the API Manager is the design of the APIs themselves. This can be done from the publishing interface or importing an existing Swagger definition (Swagger is a specification language of RESTful APIs (an architectural standard), in a nutshell Swagger hides implementation details from the consumer or developer who wants to use the API).
API’s can be published to users / developers inside your organization, outside of it, or a combination of both. Since APIs can use multiple protocols (like SOAP, REST, JSON and XML), you have the possibility to support al off them. Publishing an API is as much work as one click of a button.
Since the world changes, and with it everything else, you can govern and manage the API lifecycle. From designing and testing to publishing, depreciating and retiring; the whole lifecycle is supported.
If you haven’t already attached documentation using swagger you can also attach URLs and files to the API separately. WSO2 Identity server enables you to apply security policies to APIs (authentication and authorization).
When you want to introduce service tiers to APIs (either in usage or monetization), theWSO2 API Manager / WSO2 Business Activity Monitor lets you define these levels (e.g. gold, silver and bronze or your own levels) and analyze the usage per API, version of the API, tier or customer. You can also define your own reports.
Govern Complete API Lifecycle
The complete lifecycle is supported, from cradle to grave so to say:
• Create (develop the API);
• Publish (make the API available for consumption);
• Block (temporarily block the API);
• Deprecate (the API is still available but no longer visible due to a newer version);
• Retire (retire and remove the API from the store).
 |
|---|
| Figure 2 API and backend service life cycle elements (Source: WSO2 API Manager documentation) |
You can document an API using Swagger (but can also attach documents directly in the store). The API access can be restricted to domains/IPs so you have control from where the APIs are consumed. It is of course possible to revoke an access token (and to set the time it is valid (even forever if you want)).
You can block a subscription and restrict a complete application. OAuth2 Authorization Code Grant Type is supported (when a call is done on behalf of a third party). Finally, you can configure the execution point of mediation extensions, giving you more control.
Of course you can publish both production keys and sandbox keys (for testing APIs). If you offer public APIs to your customers or perhaps anyone who wants to use them, you can also publish the APIs to partner networks like ProgrammableWeb (a collection of API’s that is published on the internet).
The routing policies can be configured with the capabilities of the WSO2 Enterprise Service Bus. The API gateway has an extremely high performance pass-through message routing with a sub-millisecond latency so no discernable delays. You are able to enforce rate limiting (network traffic) and throttling policies (restrictions on usage based on user definable tiers).
In most cases you want to know who your user is. For this purpose you can issue user access token using the OAuth2 standard with full control over the expiration time of the token. User configurable statistics will tell you who is using what, when and how often with the WSO2 Business Activity Monitoring component. The WSO2 API Manager uses the services of the WSO2 Governance Registry.
Monitor API Usage and Performance
This version of WSO2 API Manager offers an Improved dashboard for monitoring usage statistics (filtering data for a date range, more visually appealing widgets). As said, WSO2 Business Activity Monitor and Google Analytics are supported out of the box.
Manage Developer Community
WSO2 API Manager helps you manage the developer community in a number of ways. First of all, we value the self-service that developers have, they can self sign up for API consumption and manage their accounts including the possibility of a password reset. Secondly, community building is possible via forums. Developers have the possibility to comment and rate API’s that are offered in the API Store.
Make them your own
All components are highly customizable through styling, theming and, since you have the source code as well, through code extension. To make it even easier, the storefront of the API Manager is implemented with Jaggery (a JavaScript based framework for making webpages) which is easily customizable.
You can use third party analytics and billing systems to analyze and monetize your APIs and connect to existing user stores like Active Directory, LDAP, JDBC and Apache Cassandra.
It is good to know that WSO2 does not tie you in too much. You can use APIs that are deployed in third party gateways. Single Sign-On using SAML2.0 (an open data standard for authentication and authorization) is supported so you can easily integrate with existing web apps.
Easily Deployable in Enterprise Setting
The API Manager can support all organizations, from an SME with a couple of developers and a limited amount of customers to a fortune 500 company with millions of users / developers. So, if you want to know if it is easy to deploy in an enterprise setting where there are more than just a handful users, the answer is Yes.
There is support for role based access control for managing users and authorization levels. Several common enterprise identity systems are supported like LDAP and Microsoft Active Directory, so no duplication of users. No, if you want you can have one system that controls it.
The Storefront can be deployed in DMZ for external access with Publisher inside the firewall for private control. You can have different user stores for different developer user groups.
Support for Creating multi tenanted APIs
The issue of multitenanted APIs is really not an issue with the API Manager. You can run a single instance and provide API management to multiple customers. You have the opportunity to also share APIs between different departments in a large enterprise.
Running multiple WSO2 products on the same server
The default port management console of each WSO2 product is always the same. So if you running multiple WSO2 components on the same server, what you need to do is change the port offset in the configuration file (carbon.xml) so that they will point to a different port and you can access all management consoles.
In order to do so you go to the directory in which the product was installed, go to the /repository/conf/directory and open the carbon.xml file and change the value to 1 or whatever value you would like.
The default is of course zero ,which corresponds to the port of 9443. If you change the offset value in the XML file to 1 it is of going to be https://192.168.2.10:9444/carbon and so on.
What you need to keep in mind when running several WSO2 products at the same server is the amount of memory that you going to need. You can look up in the amount of memory that is needed in the table introduced earlier. In many cases it is 2 GB with the heap size of about 512 MB memory as well for almost each product.
If you do find that the performance is going to beat this is sluggish then you’re better off moving it to different servers.
Glossary of terms
{{cta(‘e5733850-bed6-405d-bc69-6ee4c006b803′,’justifycenter’)}}
