The management of Application Programming Interfaces (APIs) is a hot topic. Discussions usually include mention of phrases like ‘exposure of your customer data’, ‘monetizing your underlying assets’ or ‘offering value add services to your customer base’.
If you have ‘assets’ or data which you think may be useful to other third parties or end customers, or if you are being driven by regulatory changes or market pressure, then an API Gateway has to form part of your solution strategy.
An API gateway allows an organisation to expose their internal APIs as external public facing APIs so that application developers can access the organisation’s data and systems functions. The capabilities of an API gateway include: management of the APIs, access control, developer portal and monetization functionality.
There are a number of offerings in the market and in this post we focus on the 3Scale offering, one of the latest entrants into the on-premise space. 3Scale, who were acquired by Red Hat, have had an API management offering as a Software as a Service for several years and have now taken this offering and packaged it for use inside the enterprise.
The good folks at 3Scale gave us access to the first beta version and we gave it a detailed examination. In our evaluation, we look at how to install it, how it works with Red Hat OpenShift and we describe some of the interesting use cases it enables. We also share some insights and top-tips.
How easy is it to Install?
The 3Scale platform comes with several deployment options, one of which is an on-premise option. For this deployment, 3Scale utilises the Red Hat OpenShift environment. The ease of integration between the 3Scale platform and OpenShift demonstrates that Red Hat have put a lot of work into getting the API Gateway working in a containerised environment. The 3Scale platform itself is deployed within OpenShift’s containers and proved relatively easy to install and run.
The architecture of the OpenShift cluster we used was a simple single master and a single minion node, as shown below.
The servers, which came configured with Red Hat Enterprise Linux (RHEL) 7.3 installed, have their own domain and the API endpoints and portals are contained within it.
Note: The basis of the installation is provided by the OpenShift documentation.
Top Tip: When copying the ssh key, make sure it is copied to the host that generated the key.
Otherwise, it can't ssh to itself and the installer notes an error.
With the installation complete, the next step was to get access to the console. This required us to edit the master configuration file (/etc/origin/master/master-config.yaml). For our purposes (and since we are an extremely trusting bunch), we used the AllowAll policy detailed here.
Following the edit, restart the master by running:
systemctl restart atomic-openshift-master.service
The OpenShift console is available at https://vm-ip-address(1):8443/console/.
To administer OpenShift from the command line, simply login to the OpenShift master node as root. Again, the AllowAll policy means that you can log in with any name and password combination but to keep things consistent you should use the same username all the time.
You can then create a project for the 3Scale deployment. After this, 3Scale can be deployed within the containers allocated by OpenShift.
(1) This is the IP Address of the master node.
3Scale has the following prerequisites:
- A working installation of OpenShift 3.3 or 3.4 with persistent storage
- An up to date version of the OpenShift CLI
- A domain, preferably wildcarded, that resolves to the OpenShift cluster
- Access to the Red Hat container catalogue
- (Optionally) a working SMTP server for email functionality.
Persistent volumes are required by the 3Scale deployment and therefore should be allocated within OpenShift prior to deploying 3Scale. For our deployment, the persistent volumes were configured using NFS shares.
Once the persistent storage was set up for 3Scale, the deployment was straightforward. We were supplied a template file for the application that just required us to provide the domain as a parameter.
Deployment involved running
oc new-app --fileamp.yml --param WILDCARD_DOMAIN=3scale.ammeon.com
and watching the logs for any issues.
After about 25 minutes the application was up and running and we were able to login.
A final setup step was to configure the SMTP server, this was a simple matter of defining and exporting variables into the OpenShift configuration.
3Scale API Gateway: sample use case
In order to exercise the platform we needed a use case to implement and an API to expose. We decided that an Internet of Things (IoT) use case made a lot of sense, not least because it’s such a hot topic right now!
So with that in mind, allow yourself to be transported on a journey through time and space, to a world where Air pollution is actively monitored everywhere and something is actually done about it. And consider the following scenario:
- There are a number of IoT devices monitoring Air Quality and Pollution levels throughout a given geographic area.
- There may be a number of different makes and types of devices monitoring, for example, carbon monoxide levels, nitrogen dioxide, particulates etc.
- A micro-service architecture could be deployed on the Beta IoT platform. Each micro-service could then process its own specific API.
- The 3Scale API Gateway would then be responsible for offering these APIs out to public third parties via the Internet to consume.
- The 3Scale API Gateway would also be responsible for managing the external access to these micro-service APIs and providing authentication and authorisation, as well as injecting policies. Auto-scaling of micro-service resources could also be provided by the 3Scale platform in conjunction with the OpenShift environment.
- The third party applications, which consume the public APIs, could then use this information to provide, for example, a Web Dashboard of pollution levels or a mobile application for users’ smartphones.
SmartCity IoT Use Case
In keeping with this, we wrote a number of user stories and scenarios around the use of the API. To implement our IOT API, which the 3Scale platform was going to ‘front’ to the outside world, we developed a basic web service written as a python flask application. The application was stored in GitHub to ease deployment to OpenShift. Rather than create a completely new project, the OpenShift example python app was forked and changed. This is the GitHub repo we used.
What do you get for your Rates?
The 3Scale platform allows you to configure rate limits for your API. The 3Scale documentation on rate limits is here.
Rate limits are set up on a per plan per application basis. This means that each application has a set of plans and each plan has the capability of setting multiple limits on each method. This is done using the Admin Portal, where specific rates can be configured. The rates work by essentially counting the number of calls made on an API method over a time period and then measuring this against the limit configured on the portal for a given application. It is possible to stop a method from being used in a plan.
Examples of rate limits are:
- 10 method calls every minute
- 1000 method calls every day
- 20 method calls every minute with a max of 100 in an hour
When a limit is exceeded, the method returns a 403 Forbidden response and, if selected, generates alerts via email and the 3Scale dashboard.
The API Gateway can be configured to use either username/password or OAuth v2.0 authentication of applications. The username/password configuration is pretty simple but OAuth authentication is a little more tricky.
You can reuse the existing system-redis service and set either REDIS_HOST or REDIS_URL in the APIcast deployment configuration (see reference). If the gateway is deployed in a project different from where the 3Scale AMP platform is, you will need to use a route.
The Analytics feature of the platform allows you to configure metrics for each of your API method calls, configuration is done via the platform dashboard. The platform will graph and show the following information:
- number of hits to your API, hits can be calls to the API or broken out into individual methods on the API
- quantity in MB or GB of data uploaded and downloaded via the API
- compute time associated with calls to the API
- count of the number of records or data objects being returned or total disk storage in use by an account.
The Developer Portal allows users to customise the look and feel of the entire Developer Portal in order to match any specific branding. You have access to nearly every element of the portal so you can basically modify to suit your own environment.
It has to be said that the documentation around how the portal is customised could be better, but if you are an experienced web developer it will probably be straightforward.
Integrating with Swagger
Swagger is a standard, language-agnostic interface to REST APIs that allows both humans and computers to discover and understand the capabilities of the service without access to source code or documentation. 3Scale allows swagger documentation to be uploaded for the APIs that are to be exposed.
We used this online editor to create the swagger documentation for the IOT API. The specification can be viewed here.
The files above are the basic documentation for the API but require updating to use in 3Scale and you need to reference this documentation. The host needs to change as does the schemes setting, and the user key need to be added. To add the file follow the instructions here.
Top Tip: One of our findings from working with the swagger documentation was that valid
security certificates need to be installed for the 3scale platform. When they aren't,
the swagger-generated curl requests returned an error.
Some documentation improvements could be made. For example, to provide an overall context or architecture overview. This would be a benefit as a starting point in order to provide the user with a better understanding of the different components ‘under the hood’. Some of the specifics which need to be modified (such as the Developer Portal web pages) could be explained better, with examples being provided for the most common tasks. Given that we were working on the first Beta version of the product, we’re going to assume that the documentation improvements will be in place prior to general availability.
What we didn’t do
Due to time and project pressures, we didn’t perform any stability, HA or performance tests. So we can only go on what been published elsewhere. 3Scale have stated that they carry out performance tests in order to provide benchmark data to size the infrastructure for given API rates. The billing mechanism wasn’t available to test so we weren’t able to set up any customer billing plans. Therefore we weren’t able to test monetization options for our fictional API.
Our experience of using both the OpenShift platform and the 3Scale API Gateway was positive and informative. It is relatively straightforward to install both OpenShift and 3Scale and get a simple API up and running. There’s a lot of ‘out of the box’ features which are useful (and perhaps essential) if you are going to deploy an API Gateway within your own premise. There’s also a good degree of flexibility within the platform to set rates, integrate to backends and customise your portals.
Overall, a good experience and a good addition to the world of API management!
Our intrepid investigation team:
Edwin Lewzey, Geoff Newson and Desi Maguire.