How To Convert From RAML to OAS To Use It in Amazon API Gateway

Suppose you have an existing RAML specification to import into Amazon API Gateway for API definition. In that case, you won’t be able to use it as is since API Gateway does not support RAML specifications. This article will guide you step by step on creating a specification file with OpenAPI from scratch from an existing RAML specification. 

If you prefer not to manually convert your RAML specification into an Open API Specification (OAS). In that case, we have compiled a helpful list of tools to assist you in this conversion process. It's important to note that the complexity of your RAML may impact the accuracy of the translation performed by these tools. Therefore, it is crucial to review the resulting conversion for any inconsistencies and address them accordingly. 

What Is OAS?

OAS stands for OpenAPI Specification, a specification language for HTTP APIs that provides a standardized means to define your API to others. 

Key features and components of an OAS document typically include:

• API endpoints: Descriptions of the API's available endpoints, such as URLs and HTTP methods (e.g., GET, POST, PUT, DELETE).
• Data models: Definitions of data structures and objects used within the API, including their properties and data types.
• Operations: Details about the operations that can be performed on the API endpoints, including request and response formats, parameters, and examples.
• Authentication and authorization: Information about how authentication and authorization are handled, such as API keys, OAuth tokens, or other security mechanisms.
• Error handling: Specifications for handling errors and status codes returned by the API.
• Versioning: Guidelines for API versioning and managing changes over time.
• Documentation: Comprehensive documentation that helps developers understand how to use the API, including examples and usage scenarios.

Tools for Translating API Specification Files

The following tools may help you to translate your API Specifications. Remember, most of the tools may translate your specifications with a few inconsistencies, so it’s crucial to review the final conversion,

• OAS RAML Converter: Converter for API specification documents, supporting back-and-forth translation of RAML and OAS (Swagger) specifications.
• OAS RAML Converter (CLI): CLI wrapper designed to allow conversion between OAS / RAML specifications via a command line interface.
• LucyBot API Spec Converter: Convert API descriptions between popular formats such as OpenAPI, RAML, API Blueprint, and WADL.
• APIMatic Transformer: Transform API Descriptions to and from RAML, API Blueprint, OAI v2/v3, and WSDL.

Converting a RAML Specification Into an OpenAPI Specification

This section will assist you if you prefer or want to learn how to translate your RAML specification into an OpenAPI Specification from scratch.

1. Reviewing a Non-OpenAPI Specification File

Let's begin by reviewing a RAML API Specification. 

This is a basic RAML specification that only retrieves flight data. It has two resources, one with a path parameter. Both resources have a get method, require a header, and have a 200 response. 

Note that the RAML specification above uses data types and examples to represent data retrieved from a server. The examples are the following.

The flight data type is the following.

The structure of the project will be the following.

2. Creating the Project

It’s important to mention that currently, Amazon API Gateway supports OpenAPI v2.0 and OpenAPI v3.0 definition files. The article will focus on creating the file in OpenAPI 3.0.0 in JSON format.

Let’s start translating the RAML files you previously reviewed into an OAS JSON file.

First, in a text editor, save a file named flights-api.json (the article uses VSCode, but you can use any text editor you want).

3. Adding Metadata to the OpenAPI Specification

In this section, we are starting to add some code to the JSON file, setting the following properties inside curly brackets: 

• openapi: with the value of “3.0.0“. This Specifies the version of the OpenAPI Specification being used, which is "3.0.0" in this case.
• info: The value will be an object containing more properties of 
  • title: with the value “Flights API, “describing the API title (You can choose the name you prefer.).
  • version: with the value “1.0.0“, referencing the version of the API (this may change if you make changes to your API by adding more resources, methods, security keys, etc.).
  • description: with the "Flights API example with OpenAPI 3.0.0" value. This is a short description of your API.

The file should be like the following.

To complete the setup, include the "servers" property to specify the API's access points. We won't add servers in this instance, so that the property will be an empty array. However, it's crucial to import it accurately into AWS Amazon API Gateway.

4. Creating Models

We must translate the data types utilized in the RAML API specification to proceed. If you look at the third line of code in flights-api.raml, you'll see that a Flight data type is defined in data-types/Flight.raml. 

Models are employed by Amazon API Gateway to construct an object and represent some flight data. 

In your text editor, return to flights-api.json and add the "components" property. Then, within the “components“ property, add another property named "schemas," where we will define the Flight model.

Within the “schemas“ property, add the “Flight“ property. This is how your model will be called in Amazon API Gateway. Within the “Flight“ property, add the following properties:

• title: with the value “Flight model."
• type: with the value “object. “
• description: with the value "Describes an object with properties of a Flight."
• properties: an object filled with all the properties used to describe the model (the next step will explain this).

OpenAPI defines the properties of a model using the syntax “propertyName“: { “type“: “propertyType“}. 

Let's add the first property, "idFlight," which will be assigned a numerical value.

Now, add the rest of the properties of the flight.

Finally, add the "required" property to prevent missing fields when sending a request with a Flight Model body.

This property will be an array with all the fields you want to be required. For this model, all fields except the idFlight field will be required. Note that the property is placed after the “description” property. 

To proceed, we need to add another model called Flights, an array of previously created Flight models. Note that we will add this model to the beginning of the "schemas" section, although it can be added anywhere. Also, instead of "properties," we will use the "items" property and reference the Flight model.

5. Setting a Resource

In this part, we are setting up the resources to define to accept requests in our API Gateway.

Next to "servers," add another property called "paths." There, we will define the resources needed. The first resource to add is "/flights". Note that all resources must have and slash (“/“) followed by the resource name.

We can select the desired methods (GET, POST, PUT, PATCH, DELETE, OPTIONS) within the newly created resource. For this scenario, we will simulate a GET method to retrieve a list of Flight data. To achieve this, we have established an array model of Flights. 

Add the "get" property and within another called "summary" to specify a short method description for documentation. 

OpenAPI specifications use "parameters" to define an array of objects containing all the properties of the parameters. 

Note: Path parameters will be explained later in this article.

Add the following properties as an object within the "parameters" array.

• name: specifies the parameter's name, which, in this case, will be a string with the value “origin.“
• in: specifies this parameter is requested as a query parameter. In this case, it will have the value of “query“.
• description: a short description of the query parameter. In this case will be the string "The origin airport code (e.g., 'SFO')."
• required: specifies if the query parameter is required (true) or not (false). In this case, the value will be wrong, saying it’s unnecessary.
• schema: defines the type of the query parameter. In this case, it will be an object with the “type“ property and the value "string."

Add another parameter with the following values;

• name: “user_id”.
• in: “header”.
• description: "The origin airport code (e.g., 'SFO').".
• schema:
  • type: “string”.

6. Creating Responses

Adding the property “responses“ is how we create responses to our method within the get property. This property for this method indicates the status code and the response.

For this example, we are adding a 200 response as a property; within the “200“ property, add the following values within curly brackets:

• description: a short description retrieved as a message with the response. For this example, it will have the string “Successful response"
• content: describes the content type of the response we are adding. Add the following values within curly brackets.
  • application/json: indicates the response's content type, adding the following values within curly brackets.
    • schema: For this example, we will have $ref to reference models created. Add the following value within curly brackets.
    • $ref: references the Flights model we have created early in this article.

7. Adding Integration Responses (Examples in RAML)

In RAML specifications, there is a possibility to simulate data retrieved from a server. We can do this by using examples. In this section, we can achieve this by creating integration responses to simulate data retrieved by a server.

Add "x-amazon-apigateway-integration" within the “get“ property. Within, add the following.

• responses: contains all responses the method could send.
  • default: defines the response it will send once the request is returned from the server.
    • statusCode: indicates the status code. It will have the string value of “200“.
    • responseTemplates: we are adding a mockup as a response, so this will be a template.
      • application/json: It will be a string representing an array of Flights, and with the application/json property, it will be sent as a JSON response. Set the following string. 

"#set($inputRoot = $input.path('$'))\n{\n    \"idFlight\": 35,\n    \"airlineName\":\"DELTA\",\n    \"code\":\"CODE721\",\n    \"price\": 323.23,\n    \"departureDate\":\"2022-28-08\",\n    \"origin\": \"SFO\",\n    \"destination\":\"LAX\",\n    \"planeType\":\"BOEING777\",\n    \"totalSeats\": 250,\n    \"emptySeats\": 35\n}"

• requestTemplates: Defines the request template for incoming requests. For this operation, the request template specifies that for requests with "application/json" content type.
  • application/json: the response should include a JSON object with a "statusCode" property set to 200.
• passthroughBehavior: Specifies the behavior when there is no match for the request. In this case, "when_no_match" indicates that the request should pass through without modification when there's no matching template.
• type: Indicates the integration type. It's set to "mock," indicating that this is a mock integration for testing purposes.

8. Adding Path Parameters

In Amazon API Gateway, we must add a resource as a property with the path parameter within curly brackets. In this case, we want to set the idFlight path parameter for a get method to retrieve a single Flight model data.

Remember to add the resources with the same indentation as the “/flights“ resource in the “paths“ property.

The next step is to add the parameters property array as we did in the “flights“ resource with the following values.

• name: “idFlight“
• in: “path”
• description: "The unique ID of the flight to retrieve."
• required: true
• schema
  • type: “string”

Note that the “in” property indicates the path that will request it. Finally, add the same user_id header we added in the “flights“ resource.

After the “parameters“ property, add the same success response we add in the “flights“ resource. The only change it will have is in the “$ref” property. This response will reference the single-flight model created early in this article.

Also, add the same “x-amazon-integreation-gateway” property to send a mock simulating data. The only change we will make is in the responseTemplates property. This response will be shorter than the “/flights“ resource integration response.

Change the value to a single-flight mock response: 

"#set($inputRoot = $input.path('$'))\n{\n    \"idFlight\": 35,\n    \"airlineName\":\"DELTA\",\n    \"code\":\"CODE721\",\n    \"price\": 323.23,\n    \"departureDate\":\"2022-28-08\",\n    \"origin\": \"SFO\",\n    \"destination\":\"LAX\",\n    \"planeType\":\"BOEING777\",\n    \"totalSeats\": 250,\n    \"emptySeats\": 35\n}"

9. Adding Validators to the OpenAPI Specification

To set up configurations that validate if a header, query parameter, or path parameter is missing in a request sent, you can add the property "x-amazon-apigateway-request-validators."

If you recall, we previously added the "user_id" parameter as a required header. With Amazon API Gateway, the request validators are responsible for verifying if the header is present in the request. If not, an error indicates that the header is missing.

We are using the following types for validation.

• validateRequestBody: validates if a body is sent into the request.
• validateRequestParameters: validates if headers, query parameters, and path parameters are sent into the request.

At the same indentation as the “paths“ property, add the "x-amazon-apigateway-request-validators" property. We will set up two types of validation to choose from.

• basic: validates if a body, headers, query parameters, and path params are sent into the request.
  • validateRequestBody: true
  • validateRequestParameters: true
• params-only: validates if headers, query parameters, and path params are sent into the request.
  • validateRequestBody: false
  • validateRequestParameters: true

As you can see, two possible configurations are defined to validate incoming requests for the API. Remember, you can define as many configurations as you want; in this case, they are “basic” and “params-only.”

The next step is to use those validators in our created methods. In the “/flights“ resource after the "x-amazon-apigateway-integration" property. Add "x-amazon-apigateway-request-validator" as a new property with the " basic " value indicating the basic validator will be applied to that method.

Do the same for the “/flights/{idFlight}” resource, changing the value to “params only."

Last Steps

Finally, you must validate if the OpenAPI specification file you created works correctly. The article How to leverage OAS & RAML in AWS API Gateway shows you how to import your Specification and test it.