Designing Restful APIs using an API-First Approach

Designing Restful APIs using an API-First Approach

Designing Restful APIs using an API-First Approach. Learn how to build an API using the API-First approach and Design First with OpenApi Specification.

I’ve been working with RESTFul APIs for some time now and one thing that I love to do is to talk about APIs.

So, today I will show you how to build an API using the API-First approach and Design First with OpenApi Specification.

First thing first, if you don’t know what's an API-First approach means, it would be nice you stop reading this and check the blog post that I wrote to the Farfetchs blog where I explain everything that you need to know to start an API using API-First.

Preparing the ground

Before you get your hands dirty, let’s prepare the ground and understand the use case that will be developed.

Tools

If you desire to reproduce the examples that will be shown here, you will need some of those items below.

  • NodeJS
  • OpenAPI Specification
  • Text Editor (I’ll use VSCode)
  • Command Line

Use Case

To keep easy to understand, let’s use the Todo List App, it is a very common concept beyond the software development community.

Disclaimer

I will hide some information to keep easy to read from the gist files, but at the end of this post, I will share the Github repository link, so you can access the full content.

Get your hands dirty

Now that you already have your environment with the needed dependencies, let’s have some fun and start to see the things happening.

The first step is to create the entry point file for the OpenAPI specification and add some content to this file.

openapi: 3.0.0
info:
  title: Todo App API
  description: Todo App API.
  version: v1
  contact:
    email: '[email protected]'
    name: 'Nicolas Takashi'
paths:
#... there more content here.

The file above is a very simple representation of an OpenAPI document, just to introduce you to the concept.

OpenAPI is a self-explanatory notation, but if you don’t know how this works yet, I recommend to use the Oficial documentation to support you during the spec design process.

Writing Path Objects

The Path Object holds the relative paths to each endpoint and their operations, let's add a file named tasks.yaml that should look like that.

get:
  operationId: get-tasks
  summary: Returns a paged list of tasks.
  description: Returns a paged list of active tasks
  tags:
    - Tasks
  parameters:
    - $ref: '../../parameters/page-parameters.yaml#/components/parameters/page'
    - $ref: '../../parameters/page-parameters.yaml#/components/parameters/pageSize'
  responses:
    '200':
      description: Success
      content:
        application/json:
          schema:
            $ref: '../../schemas/pagedTask.yaml#/components/schemas/PagedTask'
post:
  operationId: create-task
  summary: Create a task
  description: Create a new task
  tags:
    - Tasks
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '../../schemas/task.yaml#/components/schemas/Task'
  responses:
    '201':
      description: Created
      headers:
        Location:
          description: 'Location of the created task /tasks/{id}'
          schema:
            type: string

Above you can see that was added two operations, that will enable the Todo List API to create a task and get a paged list of tasks.

Now we can add the operation to enable the API to remove a task, find one specific task, and update a task, to do that we must to create a new file named tasks-with-id.yaml and add the following content.

get:
  operationId: get-task
  summary: Get task by id
  description: Return a task
  tags:
    - Tasks
  parameters:
    - in: path
      name: id
      description: Task id
      required: true
      schema:
        type: string
        format: uuid
  responses:
    '200':
      description: Success
      content:
        application/json:
          schema:
            $ref: '../../schemas/task.yaml#/components/schemas/Task'
put:
  operationId: update-task
  summary: Update a task
  description: Update a task
  tags:
    - Tasks
  parameters:
    - in: path
      name: id
      description: Task id
      required: true
      schema:
        type: string
        format: uuid
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '../../schemas/task.yaml#/components/schemas/Task'
  responses:
    '202':
      description: No Content
delete:
  operationId: delete-task
  summary: Delete a task
  description: Delete a task
  tags:
    - Tasks
  parameters:
    - in: path
      name: id
      description: Task id
      required: true
      schema:
        type: string
        format: uuid
  responses:
    '202':
      description: No content

Probably you can understand almost everything as described in the file above, but I believe the $ref notation deserves some explanation.

api restful programming developer

Bootstrap 5 Complete Course with Examples

Bootstrap 5 Tutorial - Bootstrap 5 Crash Course for Beginners

Nest.JS Tutorial for Beginners

Hello Vue 3: A First Look at Vue 3 and the Composition API

Building a simple Applications with Vue 3

Deno Crash Course: Explore Deno and Create a full REST API with Deno

How to Build a Real-time Chat App with Deno and WebSockets

Convert HTML to Markdown Online

HTML entity encoder decoder Online

What is REST API? An Overview | Liquid Web

What is REST? The REST acronym is defined as a “REpresentational State Transfer” and is designed to take advantage of existing HTTP protocols when used

An API-First Approach For Designing Restful APIs | Hacker Noon

I’ve been working with Restful APIs for some time now and one thing that I love to do is to talk about APIs.

A Simple Guide to API Development Tools

APIs can be as simple as 1 endpoint for use by 100s of users or as complex as the AWS APIs with 1000s of endpoints and 100s of thousands of users. Building them can mean spending a couple of hours using a low-code platform or months of work using a multitude of tools. Hosting them can be as simple as using one platform that does everything we need or as complex as setting up and managing ingress control, security, caching, failover, metrics, scaling.

What the difference between REST API and RESTful API?

Representational state transfer (REST) is a style of software architecture. As described in a dissertation by Roy Fielding, REST is an "architectural style" that basically exploits the existing technology and protocols of the Web. RESTful is typically used to refer to web services implementing such an architecture.

A Simple Guide to Planning API Roadmaps

APIs - the current “big thing” - offer the opportunity for modern organizations to unlock new and lucrative business models. The article below covers some tips on how to spin the API flywheel and leverage its possibilities.