Design RESTful API using Swagger OpenAPI Specification 3.0

Hi Everyone, In this article, we will discuss how we design RESTFul APIs using OpenAPI Specification(OAS). We will design RESTFul API for a To-do Application.

What is RESTful API design?

RESTful API design is the activity of describing the behavior of a web service in terms of its data structures and the actions you allow other application components to perform on its data by the principles of REST.

Why it's Important?

When we work on building a product that time design plays an important role because it can be used as a contract between the provider and the consumer. Multiple teams can work on a single application without waiting for other tasks to complete.

For Example:- You are a backend developer and there are other teams like UI & QA. So once you are not ready with your backend work they can’t integrate the work on their side. But if we have a contract or specification it's easy to test and give feedback to the backend team.

OpenAPI Specification

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

So let's start to create an API specification for To-DO App. The operation that supported in our app are following.

REST operations for To-do Application

1. Open Swagger Editor

You will see default a pet store application. Remove all the text on the left-hand side. You can write OpenAPI definitions in YAML or JSON. In this guide, we use only YAML examples but JSON works equally well.

2. Create definitions for To-do App

• We will define definitions first for info, contact, version, external documentation, etc.
• The info section contains API information: title, description (optional), version

openapi: 3.0.2
info:
  title: To-Do REST API
  version: 0.0.1
  description: REST APIS for Todo App
  contact:
    email: dev-support@thecodereveal.com
    name: Development Team

Servers

The servers section specifies the API server and base URL. You can define one or several servers, such as localhost, test & production.

servers:
  - url: 'http://localhost:8080'
    variables: {}
    description: localhost

Paths

The paths section defines individual endpoints (paths) in your API, and the HTTP methods (operations) supported by these endpoints. For example, POST /task can be described as:

paths:
  /task:
    summary: Rest Operations for Task API
    post:
      summary: Create new task
      description: ''
      operationId: createTask
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '201':
          description: New Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
            application/xml:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Bad Request
        '401':
          description: Unauthorize
      tags:
        - Tasks

Tags

A tag can be defined as a title to the group of operations for e.g we declare the tag as Tasks.

tags:
  - name: Tasks

Complete API Specification for To-Do REST API.

openapi: 3.0.2
info:
  title: To-Do REST API
  version: 0.0.1
  description: REST APIS for Todo App
  contact:
    email: dev-support@thecodereveal.com
    name: Development Team
servers:
  - url: 'http://localhost:8080'
    variables: {}
    description: localhost
tags:
  - name: Tasks
paths:
  /task:
    summary: Rest Operations for Task API
    post:
      summary: Create new task
      description: ''
      operationId: createTask
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '201':
          description: New Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
            application/xml:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Bad Request
        '401':
          description: Unauthorize
      tags:
        - Tasks
        
    get:
      summary: Get All Tasks
      description: ''
      operationId: getAllTasks
      responses:
        '200':
          description: New Task created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
        '400':
          description: Bad Request
        '401':
          description: Unauthorize
      tags:
        - Tasks
  /task/{id}:
    description: Task Operations
    get:
      tags: 
      - Tasks
      description: Get Tasks
      operationId: getTasks
      summary: Get Task
      parameters: 
      - name: id
        schema:
          type: integer
        in: path
        required: true
        description: Task Id
      responses:
        '200':
          description: Success
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Task'
    
    put:
      tags: 
      - Tasks
      description: Update Task
      operationId: updateTask
      summary: Update Task
      parameters: 
      - name: id
        schema:
          type: integer
        in: path
        required: true
        description: Task Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
          application/xml:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '200':
          description: Success
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Task'
    
    delete:
      tags: 
      - Tasks
      description: Delete Task
      operationId: deleteTask
      summary: Delete Task
      parameters: 
      - name: id
        schema:
          type: integer
        in: path
        required: true
        description: Task Id
      responses:
        '200':
          description: Success
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Task'
            
    
components:
  schemas:
    Task:
      description: Task Object
      type: object
      properties:
        id:
          type: integer
          format: int64
        title:
          type: string
          description: Task Title
        description:
          type: string
          description: Task description
        startDate:
          type: string
        endDate:
          type: string
        status:
          $ref: '#/components/schemas/TaskStatus'
    TaskStatus:
      type: string
      enum:
        - ACTIVE
        - DELETED
        - COMPLETED

You can check more definitions like responses, request body, authentication on the swagger official documentations.

https://swagger.io/docs/specification/basic-structure/

To-Do Application

Check out some other useful content on my channel. The Codereveal

Thanks.