Designing Complex REST API Structure With State Machine

Most of the developers write REST API with different HTTP methods such as GET, POST, PUT, DELETE, and HEAD. Suppose we have a micro-service where it has to handle the different states and transitions, so for that, it should be structured in a finite state machine. Basically, all the need to do is define all the states within a machine and describe transitions from one state to another.

This article is all about handling different states and transitions in REST APIs through javascript-state-machine.

What is REST API

REST stands for REpresentational State Transfer.

A RESTful API is an architectural style for an application program interface (API) that uses HTTP requests to access and use data. That data can be used to GET, PUT, POST and DELETE data types, which refers to the reading, updating, creating and deleting of operations concerning resources.

Features of REST API:

1. Scalability
2. Flexibility and portability
3. Independence

Design Principles of REST API:

1. Uniform Interface: The uniform interface lets the client talk to the server in a single language, independent of the architectural backend of either.
2. Client-Server: Loose coupling of client and server so that it can evolve individually and independently.
3. Stateless: REST API calls can be made independently of one another, it should not rely on data that is stored in the server.
4. Caching: To manage huge loads of inbound and outbound calls, the design should able to handle cacheable data. Caching is done on the client-side.
5. Layered system: Several layers operate together to construct a hierarchy that provides a more scalable and flexible application
6. Code on demand: It allows for code or applet to be transmitted via the API to use within an application.

what is a state machine?

A state machine diagram models the behaviour of a single object, specifying the sequence of events that an object goes through during its lifetime in response to events.

A state machine diagram consists of:

1. States
2. Transitions

Suppose your service wants a dedicated resource to run a particular application, this resource can be a docker container.

state machine diagram for resource creation:

Architecture:

States:

• Initializing: Initial state of the resource
• Queued: State of the resource when it is in queue
• Created: Resource created
• Running: Resource in running mode.
• Stopping: In any case of failure, stop a resource
• Stopped: Resource cleaned up

Transitions:

• Initially, a resource is in initializing state, it can either move to Stopped or Queued.
• After Queued, it can either move to Created or Stopped.
• After Created, the possible transition is Running or Stopped.
• After Running, the possible transition is Stopped in case of failure.

npm library for handling state machine: javascript-state-machine

const StateMachine = require('javascript-state-machine');

let fsm = new StateMachine({
  init: 'Initializing',
  transitions: [
    {
      name: 'updateState',
      from: '*',
      to: function (n) {
        return n;
      }
    },
    {
      name: 'queue', from: 'Initializing', to: 'Queued'
    },
    {
      name: 'create', from: 'Queued', to: 'Created'
    },
    {
      name: 'start', from: 'Created', to: 'Running'
    },
    {
      name: 'stop', from: ['Created', 'Running'], to: 'Stopping'
    },
    {
      name: 'stopped', from: ['Initializing', 'Queued', 'Stopping'], to: 'Stopped'
    }
  ],
  methods: {
    onStopped: function() { console.log('State transition to Stopped') }
  },
  data: {
    endState: 'Stopped',
  }
});

Lifecycle events: To track an action whenever any transition happens.

• onBeforeTransition
• onAfterTransition
• onTransition
• onEnterState
• onLeaveState

Helper methods:

• is(state): returns true if state is current state
• can(t): returns true, if transition t possible
• transitions(): Possible transitions from current state

Full code on GitHub repo: state-machine

Wrap up:

• Understanding of REST API
• Features if REST API
• State Machine understanding
• Resource handling state machine diagram
• Javascript state machine library and its methods

Source:

REST API Tutorial

javascript-state-machine