How To Approach Amazon API Gateway as a Mule Developer (Part I)

Amazon API Gateway

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.

What Is Amazon API Gateway?

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 To Approach Amazon API Gateway as a Mule Developer (Part I)

Defining REST APIs: Design Center With RAML vs. Amazon API Gateway

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

On the Amazon API Gateway console main page, click on the Create API button.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Select the REST API option.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Set the name to “Flights API, “set the description to “Flights API example, “ and leave the Endpoint with the default option.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

In the Amazon API Gateway console, we need to specify we want to create a resource.

Then, we have to set some configurations. We only have to set the resource name to flights. Resource paths should be filled automatically with the same name. If not, type it.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Click on the Create Resource button. The endpoint will be created.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

In the Amazon API Gateway console, to create a new method while /flights resource is selected, click on the actions button and select the create method option.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

An input with a list of HTTP methods will be displayed.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Select GET and then click the check button.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Our approach should appear like the following. From now this screen will be called and refer to /flights - GET - Method Execution.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

4. Creating a 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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Click Add header, set the header name to user_id, click the check button, and check the required box.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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. 

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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 the Create resource button. 

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Set the Resource name to /flights and change the resource path to {idFlight}. Click on the Create resource button.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

The new resource /{idFlight} should be created under the /flights GET method.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Click on the Actions button while /{idFlight} resource is selected. Click on the create method. Select GET and click on the rounded check button. 

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Set the integration type to Mock. Click the save button.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

A new method under the /{idFlight} resource should be created. From now this screen will be referred to /flights/{idFlight} - GET - Method Execution.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Click on the test button, and note there is a new path param field {idFlight}. There, you can set the value for your id.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Visit the Amazon API Gateway 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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Click on the create button, set the name to Flight, the content type to application/json, and set an optional description.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

In the Model schema input, set the value shown in the following image. How To Approach Amazon API Gateway as a Mule Developer (Part I)

Click the Create Model button at the bottom right of the screen, and your model will be on the right side of the console.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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: 

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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. 

How To Approach Amazon API Gateway as a Mule Developer (Part I)

This model indicates that it will be an array of Flights (the last model created). Finally, click on the create 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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Repeat the last steps for a RAML 1.0 Example file named Flight.raml with the following properties.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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} 

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Click on Add mapping template. Set the Content-Type to application/json and click the check rounded button. The following screen should appear.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

JSON
 
#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:

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

Then select the Flight option in the Generate template input. It should generate a template like the following.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

We are using this example but making some changes to the template. Use the following code.

JSON
 
#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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)


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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

In the Amazon API Gateway console, return to /flights - GET - Method Execution and click the Test button. The following screen should appear.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

11. Documentation

Let’s write a short documentation with RAML syntax in the Design Center. Locate the get method in /flights resource, and set a displayName and description. Do the same for the header and the query parameter.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

This is how the console in the Design Center shows the documentation we have written.

How To Approach Amazon API Gateway as a Mule Developer (Part I)

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.

How To Approach Amazon API Gateway as a Mule Developer (Part I)Replace the default value with the following code.

JSON
 
{
  "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
        }
      ]
    }
  ]
}


Summary

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.

 

 

 

 

Top