Blog

How-To: Onboarding Your API with Akamai API Gateway

May 31, 2018 · by Davey Shafik ·
Categories:

Akamai API Gateway is a brand-new product designed to help you deploy your APIs on Akamai’s cloud delivery platform to simplify governance and maximize reliability. The best way for you to learn about the impressive capabilities of API Gateway is to onboard your own API, so let’s get right to it.

The API we’ll be using in this blog post to demonstrate the onboarding process is part of our reference-app demo project, Urban Crawl.

 

Adding an API to API Gateway

 

To start using API Gateway with your API, you need to configure the gateway to let it know about each API as an endpoint with a set of resources. You can either do this manually, or you can import a Swagger or RAML API definition file.

To add an API, first login to the Akamai Luna Control Center and then go to Manage API Definitions in the Configure menu:

Next you will click the Register an API button:

Now to set up the API, click the “Import API definition” button, and choose either a JSON Swagger file, or a RAML file.

For Urban Crawl, we’re going to use a Swagger file exported from Loopback. To generate the Swagger file use the following command:

 

$ lb export-api-def -o api.json

 

You can find an example of the output here.

Once we have imported the file, you will see the API details auto-populate. At this point, we need only enter the API hostnames to complete the basic onboarding of our API:

If you also look further down the page, you can see the list of imported endpoints:

Each of those imported endpoints can be expanded to see further details like this:

Your API is now successfully onboarded. Let’s take a look at what you can do from here.

 

API Key Verification and Security at the Edge

 

A key (pun intended) feature of API Gateway is the ability to offload key verification and resource access control to the edge. To enable this, we must first configure API Gateway and set where to look for the API key. For our API, we’re going to use the HTTP header X-API-Key. To set this up, choose “Header” from the API key location dropdown:

Then set the header name:

With this configuration in place, you can save the configuration and activate it. To do this, click the Activate Version button on the overview screen for your API:

Then choose the networks to activate on (in this case, Staging and Production), enter any notes, and an email address to notify once activation is complete, and click Activate:

Lastly, you will need to add the Akamai API Gateway behavior to the property for the API itself using Property Manager. The behavior should be added to the Default rule and Enable should be set to On:

Save and activate the property, and the API Gateway will then be used for all paths defined in the API Definition.

Note: To take advantage of most of the features of API Gateway, you must use a secure property.

 

Testing Your API Gateway Configuration

 

Once you have activated both the API Definition and the property with the Akamai API Gateway behavior enabled, you can use httpie to test your configuration:

 

$ pip install httpie$ http -pHh  GET https://api.urbancrawlapp.com/api/v2/cartGET /api/v2/cart HTTP/1.1Accept: */*Accept-Encoding: gzip, deflateConnection: keep-alive Host: api.urbancrawlapp.comUser-Agent: HTTPie/0.9.9

 

HTTP/1.1 403 ForbiddenConnection: keep-aliveContent-Length: 291Content-Type: text/htmlDate: Tue, 29 May 2018 15:23:42 GMTExpires: Tue, 29 May 2018 15:23:42 GMTMime-Version: 1.0Server: AkamaiGHost

 

When we execute a request against the API, you can see that we now get a 403 response, because we haven’t specified an API key. So let’s do that now.

 

Managing API Keys

 

The last thing we need to do to enable API keys is add one or more keys to API Gateway. If you have existing users with API keys you can easily import them in either JSON, CSV, or XML format. For our new API, however, we’re going to create a brand-new key within API Gateway.

To manage API keys, choose the Manage Keys And Quotas from the Configure menu:

Next, you will add a Key Collection. Key collections are used to group API keys together to allow you to manage them as a group or to have different access control lists (ACLs) and rate limiting for different types of clients, e.g., free, paid, and enterprise API consumers.

To add a key collection, click the + button in the left navigation:

Once you give it a name, and an access control group (ACG) and optionally some notes, click Save. Now you can create your first key. This is done by clicking the Create keys button:

You can then create one or more keys. Each key has a label (which can be auto-incremented), a description, and a list of tags to allow easier management. The value of the key can be supplied or generated automatically. Here’s where you’ll create your key(s):

Clicking Save will create a new API key as seen here:

To use the API key, the client must provide it in the location specified in the API Definition, which in this case is the X-API-Key header.

Next, we need to create an access control list, or ACL. The ACL is used to determine which endpoints are accessible to the keys within the collection:

The ACL is created by clicking the Edit ACL button, and then simply choosing the API endpoints, or the entire API, to expose:

Once the updated ACL has been deployed to the Akamai network, the keys will then allow clients to access the resources defined.

You can test this by using httpie again, this time adding the argument X-Api-Key:d0a087d9-dc85-4946-8755-e2416b6a85b9 to specify the correct header and value:

 

$ http -pHhBb  GET http://api.akamaideveloper.com/api/v2/cart X-Api-Key:d0a087d9-dc85-4946-8755-e2416b6a85b9GET /api/v2/cart HTTP/1.1Accept: */*Accept-Encoding: gzip, deflateConnection: keep-aliveHost: api.akamaideveloper.comUser-Agent: HTTPie/0.9.9X-Api-Key: d0a087d9-dc85-4946-8755-e2416b6a85b9

 

HTTP/1.1 200 OKAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Origin: *Connection: keep-aliveContent-Length: 482Content-Type: application/jsonDate: Mon, 28 May 2018 23:49:58 GMT

 

In the above, you can see that API Gateway has validated the key and forwarded the request to origin, resulting in a successful response. You can further test this by supplying invalid keys, which will result in an HTTP 403 status.

 

API Quotas

 

One of the most powerful features of API Gateway is its ability to enforce client quotas across the network in real time. This allows you to scale, and protect your API.

API Quotas are applied to all keys within a collection individually, meaning that if you specify a quota of 100 requests per hour, each key will have their own pool of 100 requests to utilize.

To enable quotas, click the “pencil” edit icon next to Quota settings:

Next, toggle the Enable quota option to “Yes”. You can then choose how many requests a key can perform over a given period of time in this window:

Additionally, you can control when each of the X-RateLimit-* headers are sent. Once you’ve set things as you’d like, click Update quota to save your settings.

After these changes have been deployed to the network, you can again test by performing the same request as earlier, and now you should see the appropriate X-RateLimit-* headers in the response alongside the headers from origin.

 

Next Steps

 

We’ve barely scratched the surface of API Gateway’s features in this post; you can dramatically improve performance by enabling API caching, use JSON Web Tokens (JWT) for authentication, and add input filtering — allowing you to verify payloads meet your schema at the edge.

With Akamai API Gateway, APIs are now a first-class citizen at the edge, allowing you to achieve the same industry-leading levels of performance, offload, edge logic, and security as regular web traffic served by Akamai.

Get started now >  

Davey Shafik is a developer evangelist at Akamai Technologies.