Spring Release Defining APIs

Creating Akamai API Definitions Using Swagger

April 16, 2018 · by Jose Calvo Chaves ·

This is one in a series of posts about the Akamai 2018 Spring Release. For an overview of the Spring Release, see our post here

We introduced a bunch of new products and features in the Akamai 2018 Spring Release, including API Gateway, Bot Manager Premier, and API Protection, all of which consume API definition files to describe the endpoints, resources, methods, and parameters that compose an API.

As we built this import functionality, we discovered that knowledge of API definition languages and how they work is not universal. To help you get this most out of these new Spring Release features, I'm going to explain API definition files, how they are used, and show you how to create them.


What's an API Definition File?

Before an API developer writes a single line of code, they often create an API definition file that describes the API. These definitions provide a single source of truth about the API that can be used in many ways:

  • Planning: Definition files can be shared during product discussions for planning API functionality.
  • Implementation: Definition files can be shared with potential API consumers to inform them of the contours of the API.
  • Testing: Definition files can be the basis for testing or mocking API endpoints.
  • Documentation: Definition files can produce thorough and interactive documentation of an API.
  • Tooling: Definition files can be used to generate client SDK stubs.

These definition files are written in one of two languages: Swagger or RAML. Swagger files can be formatted as JSON or YAML, whereas RAML is only formatted as YAML. Note that both specifications will work, allowing you to properly document any API you are trying to create, but the OpenAPI Specification (also known as Swagger) has become the de-facto standard. In this post, I focus on Swagger only.


Using Swagger to Define an API

Swagger is the most widely used tooling ecosystem for developing APIs with the Open API Specification (OAS). It provides a framework to design, build, and document a RESTful API service. OAS was actually called Swagger specification in its early life. In November 2015, Smart Bear Software launched the Open API Initiative under The Linux Foundation to create an open approach for the evolution of the Swagger specification, with the hope of accelerating the standardization and implementation of it.

The reason Swagger has been able to grow so much compared to other specifications/frameworks could be because of how easy it is to understand, even for non-developers, as well as the fact that it provides a format that is effectively readable by both humans and computers.

Click here to see an example of an actual Swagger file. Below is a snapshot of what it looks like:



How to Define an API

Swagger editors give you the ability to define your API in an intuitive way. A great example of this is the one provided by In this editor, as the different entries of the API definition are updated, you’re able to see the changes reflected on the right-hand screen.

It helps to have the editor enforcing the standards of the spec while you edit it. For example, if you modify the description of the API definition in the editor on the left, you’re able to see the result on the right of the screen immediately. At the same time, if there’s an error in the syntax of the API definition, the Swagger editor displays a message with the respective line number (which you can click to take you to the actual location line), and in some cases even suggests an alternative. Take a look at the GIF below to see this in action:

Once the API definition is complete, it can be saved into YAML or JSON format. Saving the file as YAML has the advantage of being easier to read for humans (no JSON brackets), but both work well.


API Definitions at Akamai

Akamai products such as Bot Manager Premier, API Gateway, and Kona Site Defender API allow you to use an API definition file to onboard an API to Akamai. It’s a much easier way to tell Akamai about your API, instead of defining it manually.

When trying to create a new API definition via an API call, there are two ways to do it,  manually, or by uploading a definition file.


Create an Endpoint Manually

Use this method to create a new endpoint version with or without resources. This is done via a POST API call and creates the definition based on the specified parameters in the body of the request.

Below is an example HTTP request generated using Postman for a call to this API which creates an endpoint named “Akamai Security”, which points to a fake site called It requires a header named “header-101” for authentication, and an API resource pointing to /resources/{resourceId}, which supports the GET verb with a required argument called “endpoint-id”, and supports a POST with a required post body argument called “id”. If you would like to test your Akamai APIs using Postman as in this example, you can follow the Using Postman to access Akamai {OPEN} APIs Akamai Community post.


POST /api-definitions/v2/endpoints HTTP/1.1 Host: Authorization: EG1-HMAC-SHA256 Content-Type: application/json Cache-Control: no-cache Postman-Token: 400ba050-9a75-46a6-966e-0d39805a3108


{ "apiEndPointName": "Akamai Security", "description": "Test for API Blog Post", "basePath": "", "apiEndPointScheme": "http/https", "consumeType": "any", "groupId": 69962, "apiEndPointHosts": [ "" ], "contractId": "3-U3Y8U4", "securityScheme": { "securitySchemeType": "apikey", "securitySchemeDetail": { "apiKeyLocation": "header", "apiKeyName": "header-101" } }, "apiResources": [ { "apiResourceName": "cloud security", "resourcePath": "/resources/{resourceId}", "description": "resource description", "apiResourceMethods": [ { "apiResourceMethod": "GET", "apiParameters": [ { "apiParameterRequired": true, "apiParameterName": "endpoint-id", "apiParameterLocation": "path", "apiParameterType": "integer", "apiParameterNotes": null, "array": false, "apiParameterRestriction": null } ] }, { "apiResourceMethod": "POST", "apiParameters": [ { "apiParameterRequired": true, "apiParameterName": "post-body", "apiParameterLocation": "body", "apiParameterType": "json/xml", "apiParameterNotes": null, "array": false, "apiParameterRestriction": null, "apiChildParameters": [ { "apiParameterRequired": true, "apiParameterName": "id", "apiParameterLocation": "body", "apiParameterType": "integer", "apiParameterNotes": null, "array": false, "apiParameterRestriction": null } ] } ] } ] } ] }


Upon successful completion of the request, you will receive a response with an HTTP status code 201 (Created) and the following response confirming the creation of the endpoint:


{ "createdBy": "msmcenhvzmnxa4yg", "createDate": "2018-04-10T23:51:54+0000", "updateDate": "2018-04-10T23:51:54+0000", "updatedBy": "msmcenhvzmnxa4yg", "apiEndPointId": 309108, "apiEndPointName": "Akamai Security", "description": "Test for API Blog Post", "basePath": "", "apiEndPointScheme": "http/https", "consumeType": "any", "apiEndPointVersion": 319178, "groupId": 69962, "versionNumber": 1, "clonedFromVersion": null, "apiEndPointLocked": false, "stagingVersion": null, "productionVersion": null, "protectedByApiKey": false, "apiEndPointHosts": [ "" ],

Full output omitted for brevity.


Create a New API Endpoint from a Swagger File Upload

This is where the magic of Swagger or RAML files come in. With this API resource, you can register an API by simply uploading a definition file, greatly simplify the process of registering a new API at Akamai. Compare this to the manual process above.

Let's look at an example of using this API resource. I’ll be performing a file upload using the HTTPie client, which has the capability of generating a Multipart/form-data request with a single line of code. The file is a slightly modified example of the Petstore Swagger file that was previously referenced above, where only the description and hostname are changed.

If you’d like to get more details about the usage of HTTPie with the Akamai OPEN APIs, please refer to the Exploring Akamai OPEN APIs from the command line using HTTPie and jq blog post.

After installing HTTPie, enter the command below:

http --auth-type edgegrid -a default: -f POST :/api-definitions/v2/endpoints/files importFileFormat='swagger' importFile@~/api-kickstart/httpie-edgegrid/swagger.yaml contractId='3-U3Y8U4' groupId='69962'


Executing the above command will send a Multipart/form-data POST that specifies a file with format ‘swagger’ with name ‘swagger.yaml ’ which will be uploaded to create an API definition under the contract ID '3-U3Y8U4' and the Group ID (also referred as ACG) ‘69962’. If the call is successful, it returns a 201 status code response like this:


HTTP/1.1 201 Created Connection: keep-alive Content-Length: 37862 Content-Type: application/json Date: Wed, 11 Apr 2018 03:22:44 GMT Location: /api-definitions/v1/endpoints/309160/versions/ + 1 Server: Apache-Coyote/1.1 X-Application-Context: api-definitions:production,enable-metrics,docker-secrets,security-shared-db:12124 X-Trace-Id: b9d76688900c9357


{ "akamaiSecurityRestrictions": {}, "apiCategoryIds": [], "apiEndPointHosts": [ "" ], "apiEndPointId": 309160, "apiEndPointLocked": false, "apiEndPointName": "Swagger is my friend", "apiEndPointScheme": "http", "apiEndPointVersion": 319138, "apiResources": [ { "apiResourceClonedFromId": null, "apiResourceId": 23597, "apiResourceLogicId": 25157, "apiResourceMethods": [ { "apiParameters": [ { "apiChildParameters": [ {

Full output omitted for brevity.

For more information on Akamai APIs, please refer to our API documentation.

And for a chance to ask our product experts about defining and protecting your APIs, register for our 2018 Spring Release webinar, live on May 3rd.