Do you want to create your first API in Amazon API Gateway but don’t know where to start? Plus, you have experience defining API Specifications in RAML with Design Center, and you are wondering if that knowledge can be leveraged.
If you have defined API specifications in Anypoint Platform’s Design Center with RAML in the past, understanding and working with Amazon API Gateway can be an easy lift. While RAML is a modeling language and Amazon API Gateway is a service (and are, by definition, tools for different purposes), we can leverage your knowledge.
Follow this article for a step-by-step into Amazon API Gateway via a comparison with what you usually do with Design Center and RAML.
Note: If you already have an OpenAPI Specification (OAS) and want to kickstart the creation of your API in AWS API Gateway, follow this link to learn How to leverage OAS / RAML in AWS API Gateway
To effectively use Amazon API Gateway, it's crucial to have a basic understanding of APIs, such as resources, methods, status codes, responses, query parameters, path parameters, headers, and body requests. If you're unfamiliar with these concepts, we suggest learning the basics before diving into this article.
To effectively use Amazon API Gateway, it's crucial to have a basic understanding of APIs, such as resources, methods, status codes, responses, query parameters, path parameters, headers, and body requests. If you're unfamiliar with these concepts, we suggest learning the basics before diving into this article.
Amazon API Gateway is a fully managed service provided by Amazon Web Services that allows developers to create, publish, monitor, and secure APIs at any scale. Using API Gateway, you can build RESTful APIs and WebSocket APIs that enable real-time two-way communication applications. API Gateway supports containerized and serverless workloads, as well as web applications Some of the benefits of this service are efficient API development, performance at any scale, cost savings at scale, easy monitoring, flexibility, and security controls. How Amazon API Gateway works.
Let's start defining an API step by step. First, we’ll recreate how you usually do it with Design Center and then guide you on how to do it with Amazon API Gateway.
1. Creating the API definition
We can create our API from scratch or import an existing file in the Design Center and Amazon API Gateway. In this case, we will make the API from scratch.
On the Design Center main page, click the Create button and select New API Specification.
Creating the API definition - Step 1 In the Design Center
In the Design Center, we have a lot of definition languages to choose from. This doesn’t happen in Amazon API Gateway because we’ll usually do the definitions in the API Gateway console.
In Design Center, in the prompt window, set the project name to “Flights API,” RAML 1.0 as a Specification Language, and click the Create API button. The project should be created.
Creating the API definition - Step 2 In the Design Center
On the Amazon API Gateway console main page, click on the Create API button.
Creating the API definition - Step 1 In the Amazon API Gateway console
Select the REST API option.
Creating the API definition - Step 2 In the Amazon API Gateway console
Set the name to “Flights API, “set the description to “Flights API example, “ and leave the Endpoint with the default option.
Creating the API definition - Step 3 In the Amazon API Gateway console
2. Creating a resource
At this point, we only have our API’s name. Then, we will create an endpoint called flights to receive requests from different HTTP verbs.
We must write the correct RAML syntax in the Design Center, and the endpoint will be created.
Creating a resource - Design Center
In the Amazon API Gateway console, we need to specify we want to create a resource.
Creating a resource - Step 1 in the Amazon API Gateway console
Then, we have to set some configurations. We only have to set the resource name to flights. Resource path should be filled automatically with the same name. If not, type it.
Creating a resource - Step 2 in the Amazon API Gateway console
Click the Create Resource button. The endpoint will be created.
Creating a resource - Step 3 in the Amazon API Gateway console
3. Creating a method
We must write the correct RAML syntax in the Design Center to create a method. In this case, we will create a get method.
Creating a method - Design Center
In the Amazon API Gateway console, to create a new method while /flights resource is selected, press the actions button and select the create method option.
Creating a method - Step 1 in the Amazon API Gateway console
An input with a list of HTTP methods will be displayed.
Creating a method - Step 2 in the Amazon API Gateway console
Select GET and then click the check button.
Creating a method - Step 3 in the Amazon API Gateway console
A new GET method will be created. Amazon API Gateway is more complex than an API specification because we must establish several settings to integrate a backend with our API.
Creating a method - Step 4 in the Amazon API Gateway console
For this exercise, we will use mocks to represent our Flights data. We won’t integrate any backend service to our API. Select Mocks as Integration type and click the Save button.
Creating a method - Step 5 in the Amazon API Gateway console
Our approach should appear like the following. From now this screen will be called and refer to /flights - GET - Method Execution.
Creating a method - Step 6 in the Amazon API Gateway console
4.- Creating headers
In Design Center, using the correct RAML syntax, we have to write the corresponding code to define a header and set whether it is required. In this case, it will be necessary.
Creating headers - Design Center
In the Amazon API Gateway console, click on Method Request in /flights - GET - Method Execution and expand HTTP Request Headers. The following screen should appear.
Creating headers - Step 1 in the Amazon API Gateway console
Click Add header, set the header name to user_id, click the check button, and check the required box.
Creating headers - Step 2 in the Amazon API Gateway console
Click on the Edit button in the Request validator. A select input should appear. Select the option Validate body, query string parameters, and headers. Click the check rounded button to save the configuration.
Now, both of our APIs require a header named user_id.
Creating headers - Step 3 in the Amazon API Gateway console
5.- Creating query parameters
In Design Center, using the correct RAML syntax, we have to write the corresponding code to define a query parameter, set the name to the origin, and type the string, and in this case, it will not be required.
Creating query parameters - Design Center
In the Amazon API Gateway console, select Method Request in /flights - GET - Method Execution and expand URL Query String Parameters. The following screen should appear.
Creating query parameters - Step 1 in Amazon API Gateway console
Click on Add query string, set the name to the origin, and click the check button. This query parameter won’t be required, so there is no need to check the Required box.
Creating query parameters - Step 2 in Amazon API Gateway console
6.- Creating a dynamic URI path parameter
Using the correct RAML syntax in Design Center, we must write the resource with the path param we want to create. In this example, we will create an idFlight path param to retrieve flight data with that id.
Creating a dynamic URI path parameter - Step 1 in Design Center
Remember to write the method at the same indentation as the first get method. Set a GET method for this resource and its required user_id header.
Creating a dynamic URI path parameter - Step 2 in Design Center
In the Amazon API Gateway console, to create a resource with a path param, be sure the /flights resource is selected and, click the Actions button, select Create the resource button.
Creating a dynamic URI path parameter - Step 1 in the Amazon API Gateway console
Set the Resource name to /flights and change the resource path to {idFlight}. Click on the Create resource button.
Creating a dynamic URI path parameter - Step 2 in the Amazon API Gateway console
The new resource /{idFlight} should be created under the /flights GET method.
Creating a dynamic URI path parameter - Step 3 in the Amazon API Gateway console
Click on the Actions button while /{idFlight} resource is selected. Click on the create method. Select GET and click on the rounded check button.
Creating a dynamic URI path parameter - Step 4 in the Amazon API Gateway console
Set the integration type to Mock. Click the save button.
Creating a dynamic URI path parameter - Step 5 in the Amazon API Gateway console
A new method under the /{idFlight} resource should be created. From now this screen will be referred to /flights/{idFlight} - GET - Method Execution
Creating a dynamic URI path parameter - Step 6 in the Amazon API Gateway console
Click on the test button, and note there is a new path param field {idFlight}. There, you can set the value for your id.
Creating a dynamic URI path parameter - Step 7 in the Amazon API Gateway console
7.- Creating Models and creating DataTypes
We are almost ready to send our first request to our APIs, but first, we need to define a data type that will represent an object containing properties and values for flight data.
In the Design Center, inside the project, we have to create a new folder named 'data-types'; inside that folder, we need a RAML 1.0 Data Type file called Flight.raml.
The properties of the data type file are the following.
Creating DataTypes - Design Center
In Amazon API Gateway, models are used to represent the structure of an object that contains data. This section of the article provides a basic explanation of how to create models in Amazon API Gateway. To learn more about Models with JSON schema, click here.
Returning to the Amazon API Gateway console, click on the Models link located in the left panel of the console. The following screen should appear.
Creating Models - Step 1 in Amazon API Gateway console
Click on the create button, set the name to Flight, the content type to application/json, and set an optional description.
Creating Models - Step 2 in Amazon API Gateway console
In the Model schema input, set the value shown in the following image.
Creating Models - Step 3 in Amazon API Gateway console
Click the Create Model button at the bottom right of the screen, and your model will be on the right side of the console.
Creating Models - Step 4 in Amazon API Gateway console
Click on the Create button again to create a new model. Set the name to Flights, Content-Type to application/json, the description “Defines an array of Flights model, “ and the Model Schema as the following:
Creating Models - Step 5 in Amazon API Gateway console
The value {your-api-id} in the $ref property must be changed to your Amazon API. Otherwise, the console won't be able to create the Flights model. The API ID can be found at the top of the console next to the Flights API link, as shown below.
Creating Models - API ID in Amazon API Gateway console
This model indicates that it will be an array of Flights (the last model created). Finally, click on the make model button at the bottom right of the console, and your Flights model will be created and located on the left side of the console.
8.- Mocking responses
Once we have created the models and data types, the next step is to create an object with representative data to simulate a response from the server.
In the Design Center, inside the project, we have to create a new folder named 'examples,' and inside that folder, we need to create a RAML 1.0 Example file called Flight.raml
The properties of the Flights.raml file is the following.
Mocking responses - Step 1 in Design Center
Repeat the last steps for a RAML 1.0 Example file named Flight.raml with the following properties.
Mocking responses - Step 2 in Design Center
Amazon API Gateway does not have examples. Instead, they refer to this functionality as Mock Integrations. For this exercise, we are not calling any backend service to retrieve actual data from a database; instead, we are simulating data.
To create a mock integration in the Amazon API Gateway console, click on the Resources link on the left side, then click the GET method, and the following screen should appear.
Mocking responses - Step 1 in Amazon API Gateway console
Click Integration Request. Be sure the Mock checkbox is chosen as the Integration type. Expand Mapping Templates. Choose or add an application/json mapping template. The screen should appear like the following.
The template input should be generated automatically with a status code. If not, the following JSON code should work: {"statusCode": 200}
Mocking responses - Step 2 in Amazon API Gateway console
Return to /flights - GET - Method Execution and click Integration Response. Expand the 200 response and then the Mapping Templates section. The screen should be like the following.
Mocking responses - Step 3 in Amazon API Gateway console
Click on Add mapping template. Set the Content-Type to application/json and click the check rounded button. The following screen should appear.
Mocking responses - Step 4 in Amazon API Gateway console
Click on the Generate template, select input, and notice there are four options to generate a template. Click on the Flights option. The Amazon API Gateway console should generate a template like the following.
Mocking responses - Step 5 in Amazon API Gateway console
The Amazon API Gateway creates a mapping template based on the Model created earlier in this article. However, we will not be using that template in this case. Instead, input the code in the image below and click the save button.
#set($inputRoot = $input.path('$'))
[
{
"idFlight": 35,
"airlineName":"DELTA",
"code":"CODE721",
"price": 323.23,
"departureDate":"2022-28-08",
"origin": "SFO",
"destination":"LAX",
"planeType":"BOEING777",
"totalSeats": 250,
"emptySeats": 35
},
{
"idFlight": 36,
"airlineName":"AMERICAN",
"code":"CODE987",
"price": 451.51,
"departureDate":"2023-12-03",
"origin": "CLE",
"destination":"SFO",
"planeType":"BOEING777",
"totalSeats": 250,
"emptySeats": 20
}
]
Amazon API Gateway console should be like the following:
Mocking responses - Amazon API Gateway console
Let's repeat all the steps for the GET Method in /{flights} resource.
Click on Integration response in /flights/{idFlight} - GET - Method Execution. Expand the 200 response and then the Mapping Templates section. Add a Mapping template with the value application/json. Finally, click on the check rounded button.
Mocking responses - Step 6 in Amazon API Gateway console
Then select the Flight option in the Generate template input. It should generate a template like the following.
Mocking responses - Step 7 in Amazon API Gateway console
We are using this example but making some changes to the template. Use the following code.
#set($inputRoot = $input.path('$'))
{
{
"idFlight": 35,
"airlineName":"DELTA",
"code":"CODE721",
"price": 323.23,
"departureDate":"2022-28-08",
"origin": "SFO",
"destination":"LAX",
"planeType":"BOEING777",
"totalSeats": 250,
"emptySeats": 35
}
}
Finally, click the save button and the success response for GET /{idFlight} will be created.
Mocking responses - Step 8 in Amazon API Gateway console
9.- Creating a success response
In Design Center, using the correct RAML syntax, we have to write the corresponding code to define a 200 success response. Write 200, define a body, this response is an application/json, type Flight[], and add the example created importing with the !include syntax. The success response will be created.
Creating a success response - Design Center
In the Amazon API Gateway console, go back to /flights - GET - Method Execution and click Method Response. The 200 response should be created. Expand 200 response, and you will see the response body has an empty model. Click the Edit button on the Response Body and select the Flights model.
Creating a success response - Step 1 in the Amazon API Gateway console
Follow the previous steps to generate a successful response for the GET method in the /{idFlight} resource, but in this case, instead of Flights, choose Flight as the Model.
Creating a success response - Step 2 in the Amazon API Gateway console
10.- Testing the API
We can test the API specification in the Design Center in the API console. We will test the first endpoint we created with the GET method.
Click on the GET method, click the Try it button, and set the user_id header to any value. Click the Send button, and a 200 response should appear with the Flights data.
Testing the API - Design Center
In the Amazon API Gateway console, return to /flights - GET - Method Execution and click the Test button. The following screen should appear.
Testing the API - Step 1 in the Amazon API Gateway console
Click on the test button. A 400 response should be returned with a message requiring a parameter named user_id is missing in your request.
Testing the API - Step 2 in the Amazon API Gateway console
To avoid this response, set the value to user_id:myUser. Click the test button again, and a 200 response should be returned with the Flight data.
Testing the API - Step 3 in the Amazon API Gateway console
11.- Documentation
Let’s write a short documentation with RAML syntax in the Desing Center. Locate the get method in /flights resource, and set a displayName and description. Do the same for the header and the query parameter.
Documentation - Design Center
This is how the console in the Design Center shows the documentation we have written.
Documentation - Design Center
In Amazon API Gateway, documentation for resources, methods, query parameters, or headers must be written in JSON format. This section of the article explains how to document your API in Amazon API Gateway. To learn more about documentation in Amazon API Gateway, click here.
Returning to the Amazon API Gateway console, go back to /flights - GET - Method Execution, and in the upper right corner should be a book button. Click on it. The following screen should appear.
Documentation - Step 1 in Amazon API Gateway console
Replace the default value with the following code.
{
"description": "Retrieves information about flights,"
"pathParams": {},
"body": {},
"queryParams": [
{
"origin": {
"required": false
}
}
],
"responses": [
{
"200": [
{
"idFlight": 4,
"airlineName": "DELTA",
"code": "ER04kg",
"price": 532,
"departureDate": "2015-02-12T00:00:00.000Z",
"origin": "MUA",
"destination": "PDX",
"emptySeats": 30,
"planeType": "Boeing 737",
"totalSeats": 150
},
{
"idFlight": 36,
"airlineName": "AMERICAN",
"code": "CODE987",
"price": 451.51,
"departureDate": "2023-12-03",
"origin": "CLE",
"destination": "SFO",
"planeType": "BOEING777",
"totalSeats": 250,
"emptySeats": 20
}
]
}
]
}
Differences
Similarities
Conclusions
You already know the basic concepts for creating resources, methods, and documentation in the RAML API specification and Amazon API Gateway. Now, you can develop more strategies for your API in Amazon API Gateway and configure additional settings, such as security API Keys, or connect your API to accurate backend services like Lambda.
The process to create an API may be the same, but remember that RAML is a language for API specification. At the same time, Amazon API Gateway is a complete API management solution provided by AWS. Depending on your requirements and the ecosystem you're working with, you may choose one or both tools to design and manage your APIs.
