Designing Your First REST API – Part 2

This is the second part of my REST API guide, where I’ll be focusing on designing a simple API using SwaggerHub. I will explain the basic functionalities of the SwaggerHub editor and the Open API Specification. My previous article covered the basic concepts of REST APIs.

You might also like: 

Introduction

OpenAPI

OpenAPI is a format of writing an API definition to describe the structure of the API to humans as well as machines. An OpenAPI file allows you to describe your entire API, including:

• Available endpoints and operations on each endpoint

• Operation parameters input and output for each operation

• Authentication methods

• Contact information, license, terms of use, and other information

OpenAPI Specification 2.0 can be found here.

Swagger

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document, and consume REST APIs. The major Swagger tools include:

• Swagger Editor – browser-based editor where you can write OpenAPI specs

• Swagger UI – renders OpenAPI specs as interactive API documentation

• Swagger Codegen – generates server stubs and client libraries from an OpenAPI spec

In my humble opinion, the main advantage of using swagger to design an API is the ability to generate interactive and self-descriptive documentation. On the other hand, we can generate server and client stubs using the same swagger definition for over 40 different programming languages.

Get Started With SwaggerHub

Actually, Swagger Editor is the official and free UI editor available to write swagger definitions. SwaggerHub is an extended and commercial edition that supports a few more features such as goto definition and collaboration. Since they allow us to create free accounts in SwaggerHub, we can use it rather than the swagger editor.

First things first. If you haven’t already, create a free account here. Once you log in, you will see the interface shown below. Click on Create New -> Create New API to start designing your very first REST API.

Select Simple API as the template, provide a name (BookStore) to your API, and click on Create API button. This will create a new swagger definition with a sample API named Simple Inventory API.

Basic Elements of a Swagger

Let’s look at the basic elements in a swagger definition.

At the top of the file, we have the version; this will be either 2.0 or 3.0, which is the latest version.
Then, we have a block named info, which contains the API’s basic information, such as its name, description, version, etc.

The next element is paths. These are the URL paths in your API. Each path can have one or more operations. In the sample inventory API, only one path exists called /inventory and that path has two operations as GET and POST.

The next element would be definitions, where we can define reusable components and refer them inside paths.

There are few other elements in the Swagger:

• host — Defines the hostname of the API

• basePath — Defines any base paths that should appear before defined paths

• schemes — Can have values http, https, ws, wss

Bookstore API Definition

Let’s start by defining our own API. I have added the skeleton of the API in my previous post. First, paste the following into your swagger editor to begin the definition.

swagger: '2.0'
info:
    title: Book Store API
    description: This is an API for an online bookstore
    version: v1
paths:
    /books:
        get:
        post:
    /books/{book-id}:
        get:
        put:
        delete:
    /books/{book-id}/reviews:
        get:
        post:
    /books/{book-id}/reviews/{review-id}:
        put:
        delete:
definitions:
    # Added by API Auto Mocking Plugin
    host: mybookstore.com
    basePath: /api/v1
    schemes:
        - https

Don’t mind the errors for now. We’ll get them fixed soon. When you add the above into the editor, the UI should look like below, with our bookstore API paths.

Since our API has two resources, books and reviews, we need to define those two objects in our swagger.

definitions:
    Book:
        type: object
        required:
            - id
            - name
            - author
            - price
            - reviews
        properties:
            id:
                type: string
                example: B10001
                description: Unique id of the book.
            name:
                type: string
                example: The Adventures of Tom Sawyer
                description: Name of the book.
            author:
                type: string
                example: Mark Twain
                description: Author of the book.
            price:
                type: string
                example: $4.90
                description: Price of the book.
            reviews:
                type: array
                description: Reviews of the book.
                items:
                    $ref: '#/definitions/Review'
    Review:
        type: object
        required:
            - id
            - score
            - comment
            - reviwer
        properties:
            id:
                type: string
                example: R1001234
                description: Unique id of the review.
            score:
                type: string
                example: 4.3
                description: Review score.
            comment:
                type: string
                example: Good book to read.
                description: Review comment.
            reviwer:
                type: string
                example: vihanga
                description: Reviewer.

A single book element has multiple reviews. Notice how we’ve referenced the Review object in the book object. Add the above part at the end of the swagger definition and edit the GET request of the path /books/{book-id}.

/books/{book-id}:
    get:
        summary: Retrieve the book resource indentified by the book-id.
        operationId: getBook
        description: Retrieve the book resource indentified by the book-id.
        responses:
            200:
                description: Search results matching the given criteria.
                schema:
                $ref: '#/definitions/Book'

Now the UI will regenerate and you can expand the GET /books/{book-id} and see the sample response as below.

Now you have a basic understanding of the task. You can find the completed swagger definition for the bookstore here from the SwaggerHub itself; the YAML file can be found here. Explore it carefully and try to develop a new one on your own.

Hope this helped. Cheers!

Further Reading