Codeless API reshaping with AWS API Gateway
“Client-specific needs”
As the sales team entered the office with a large grin, the dev team began to fear what they see as irrelevant and as a design hell: the infamous “client-specific needs” !
The most feared words across most of dev teams.
This time, a huge prospect likes our product. He likes it so much that he wants to integrate a great part of it to his own ecosystem. Yay!
Unfortunately, our public APIs lack the required endpoints, but our private APIs provide the ones that would allow our prospect to properly integrate our service into their system.
Exposing these APIs was never the plan, and we have to ask ourselves two questions:
- How can we continue to make change to these APIs without impacting the client?
- How can we spend as little time as possible on developing and providing support for this?
We decided to find a solution to expose only a subset of our API, to ease the integration process of our client.
It came out it was actually possible and quite easy, using AWS API Gateway.
What were our options?
Our first idea was to add another route in our Rails application (we are developers after all, so our initial response to most questions is code!).
After carefully considering all the drawbacks that it would introduce (adherence to the API forbidding to split the service or change the routes at will, the need for a new rate limiting mechanism as our internal APIs does not include one, etc…), we tried to find an alternate solution outside of our Rails application.
We decided to turn to an API management system to gain flexibility, and after considering Kong, and other proprietary solutions, we decided to give a try to AWS API Gateway, which is managed (no need for sys admin work) and really flexible.
What is the API Gateway from AmazonWebServices?
AWS API Gateway allows us to declare an API structure, composed of resources and actions (HTTP verbs) and link them to specific integrations:
- AWS Lambda: execute an AWS Lambda function and forward its return
- HTTP proxy: forward request to another API
- Mock integration: return fake data
- AWS service proxy: trigger any action of any AWS service
Using the analogy of Object Oriented Programming, you can look at API Gateway as a factory, a stage as an instance and your resource collection as a class definition.
A stage can be parameterized with throttling, burst limit or specific client certificates for example. This is of paramount importance to us because we have clients with very different needs so being able to fine tune each environment is a must.
Changing an HTTP verb
Assuming you already have an API exposing the following endpoints:
GET: api/v1/clients/{client_id}/appsGET: api/v1/clients/{client_id}/apps/{app_id}/install
You want to:
- Avoid exposing to your client the notion of client_id (for security and simplicity).
- Configure both your staging and production environments (hence the creation of an URL stage variable).
- Transform the second request (install) to a more relevant POST action.
You can create an API Gateway that will follow this setup:
GET: api/apps => GET: https://${stageVariables.url}/api/v1/clients/${stageVariables.client_id}/apps/POST: api/apps/{app_id}/install => GET: https://${stageVariables.url}/api/v1/clients/${stageVariables.client_id}/apps/{app_id}/install
Then, you can deploy your API to a new stage and set stageVariables.url and stageVariables.client_id.
Presto, your new client-specific API is deployed! You can now create and share it for any new client needing specific endpoints.
Changing a key in a json response
Imagine your server’s json response changes from:
to
You can modify the response from your server to return the expected “host1” key to your client. This can be done directly through the API Gateway’s web interface, the body mapping templates of the HTTP proxy integration response configuration (go to Resources, select the action you need to update, click on Integration Response, expand the response type you want to edit (200 for example), and expand its Body Mapping Templates section).
Now, your API Gateway will return the expected “host1” key, as it used to.
Advanced manipulation
When you need to do more advanced processing (adding timestamps, values typing, aggregation, …), you can use an AWS Lambda function to manipulate data on the fly.
And the icing on the cake…
The first million of API calls is free during 12 months.
Then, it costs around $4 per million API calls received, plus a little bit for the data transfer and caching if you choose to use it.
API Gateway also fully supports Swagger integration, allowing you to import a new API from a JSON or YAML file in a few clicks.
From Swagger, you can then generate a client SDK for your APIs for a large selection of languages and frameworks. This will make the integration to the client silk smooth…It is also available from the AWS console, but only for JavaScript, iOS or Android.
This solution allows us to provide the custom API endpoints our customers need, without writing a line of code. Win!
The first setup can take a little while, because you have to choose carefully the APIs you want to expose and input them into the Gateway API console. But after that, configuration modifications are painless.
And with the possibility to create new parameterized stages via API, there’s nothing preventing us from adding automation to this process and using it with any other client…
This article was written by Appaloosa’s dev team:
Benoît Tigeot, Robin Sfez, Alexandre Ignjatovic, Christophe Valentin
Want to be part of Appaloosa? Head to Welcome to the jungle.
