How to Describe RESTful APIs using RAML and Swagger?

This tutorial is adapted from Web Age course Api Management Fundamentals for Architects Training.

1.1 Why to describe RESTful APIs?

To make RESTful services useful, Service APIs must be described and published. Client need to be able to find API descriptions. APIs must be described in sufficient detail so that clients can select services, create service requests, interpret service responses, choose service endpoints and understand service status codes.

1.2 History

Since REST is not a standard (or collection of standards) there is no standard way to describe or publish RESTful APIs. SOAP has a standard for service descriptions called WSDL. There have been a number of attempts to come up with a means of defining RESTful APIs like WSDL 2.0, WADL, OData, OpenAPI, RAML and API Blueprint.

1.3 Ad-hoc Interface definitions

The reality is that many organizations use ad hoc service definitions like Excel Spreadsheet, Word Document, Web Page and Wiki Page. Some organizations lack even an ad hoc method of creating service definitions.

1.4 Modern Choices

Two service description languages seem to be gaining traction in RESTful services are OpenAPI (Swagger) and RAML. While it seems that the community may be coalescing around OpenAPI, e.g. MuleSoft (originators of RAML) has joined the Open API Initiative, some people comment that when compared to Swagger and WADL, RAML appears to strike a better balance between technical aspects and human readability along with offering simple API versioning feature. 

1.5 Stacking Up Open API vs RAML

Source: https://www.q-perior.com/en/blog/openapi-and-raml-in-comparison/

1.6 Open API vs RAML: Advantages and Disadvantages

Source: https://www.q-perior.com/en/blog/openapi-and-raml-in-comparison/

1.7 What is RAML?

RAML is RESTful API Modeling Language. It is based on YAML. YAML is n’t Markup Language. It uses Python-style indentation. 

1.8 What are the steps to build A RAML API Description?

• Build the Root

• List Resources

• Define the methods

• Define the query parameters

• Add query parameter detail

• Enter responses

This approach starts by outlining the service operations and iteratively adding detail

1.9 ROOT

This is the case information for the API

#%RAML 1.0

—

title: Car Inventory API

baseUri: http://inventory.cars.com/{version}

version: v1

1.10 List Resources

REST is about resources. This API has only one base level resource. List the resources:

/cars:

   /{id}

     /make

1.11 Define Methods

List the (HTTP) Methods

/cars:

     get:

      /{id}

      get:

      post:

      put:

      patch:

      delete:

      /make

        get:

1.12 Define Query Parameters

List any query parameters

/cars:

   get:

    query parameters:

    make:

/{id}

   get:

   post:

   put:

   patch:

   delete:

   /make

     get:

1.13 Enter Responses

Map to HTTP status codes

/cars:

   /{id}

      get:

         description: Retrieve a specific car

         responses:

             200:

               body:

                  application/json:

                    example: |

                       {

                         “data” : {

                            “id” : 1234,

                            “make” : “Ford”,

                            “model” : “Mustang”,

                            “year” : 1969

                        },

                         “success” : true,

                         “status” : 200

                      }

1.14 Open API (Swagger)

It is originally called Swagger. It has multiple syntax choices, YAML and JSON. Some of the tools that support for Open API are Swagger Editor – Online editor, Swagger Codegen – generate server/client stubs from API definition, Swagger UI – embedded into service to create interactive documentation. Swagger specification can be found at https://swagger.io/specification/.

1.15 Swagger Versions

Swagger v.3 (Open API 3) is the latest Open API spec introduced early 2017.

• Changes touched a number of areas:

  • Format:

    • OpenAPI 3 now specifies YAML should be 1.2

    • Better JSON Schema support (added: oneOf, anyOf, nullable, etc.)

  • URL structure

    • New path templating feature with a “variable” property

  • Components

    • Standardized the concept of “components”

  • Request format, etc.

• Swagger 2.0 service descriptions can be ported to Open API 3 without much pain

• See https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/ for more details

1.16 Swagger Editor

It is an Online tool. It displays OpenAPI service definition in editable window and shows operations on right side.

1.17 Swagger Editor

Expanding operations gives more details.

1.18 Swagger Editor

It shows model object details (types).

1.19 Swagger Codegen

It is an online tool to generate server and/or client stubs. It supports multiple languages.

1.20 Swagger UI

It is deployed with service and It has similar features to Swagger Editor.

1.21 Swagger UI

Tools to test service

1.22 Swagger UI

Enter values and execute requests:

1.23 Swagger UI

with Swagger, you can view responses. Since this was a POST request a new resource was created

The response

No body

Status Code 201 – Created

Location header is the URI of the newly created resource

1.24 Swagger UI

Swagger UI generate equivalent cUrl commands

1.25 OpenAPI Service Description

The Swagger UI also displays the Open API service description in JSON. The JSON format used is not particularly readable.

1.26 Pretty Printed OpenAPI Service Definition

1.27 Summary

In this tutorial we discussed

• Describing RESTful APIs

• History

• RAML

• Open API (Swagger)