A RESTFul API Guidelines and Best practices

A RESTFul API Guidelines and Best practices

Introduction

The best thing about software is its flexibility: It can be programmed to do almost anything. The worst thing about software is also its flexibility: The "almost anything" characteristic has made it difficult to plan, develop, monitor, and control software development (Walker Royce, 1998).

What is an API?

API (Application Programming Interface) is a piece of software that is used by another piece of software, in order to allow the application to interact (exchange data) to each other via some define calls or requests that can be made, how to make them, the data format that should be used, the conventions to follow, and et al.

The RESTFul Architecture

  • REST stands for REpresentational State Transfer, its core essential the concept in any REST API is the resource.
  • A resource is an object with a type, associated data, relationships to other resources, and a set of methods (verbs) that operate on it.
  • A URL (Uniform Resource Locator) on the other hand, is the path that the resource can be located with an associated bagpack of some actions that can be performed on it.

The core fundamental principles of a REST API

  • Separate APIs into logical resources
  • Expose structured, resource-based URLs
  • Use HTTP methods (verbs) extensively
  • Send the data as JSON (JavaScript Object Notation)
  • Be stateless

API Endpoints & Methods

Endpoints of any REST API should contain only resources (nouns) and use HTTP methods (verbs) for actions. Methods are a set of actions to be performed on resources.

HTTP Response status code categories

  • 100 – 199 (Informational responses)
  • 200 – 299 (Successful responses)
  • 300 – 399 (Redirects)
  • 400 – 499 (Client errors)
  • 500 – 599 (Server errors)

Versioning

When API are being consumed by other applications, upgrading the APIs with some changes would also lead to breaking the existing services contract - this has been notice by a lot of applications that provide API services. It is a best practice to always prefix all your URLs with /api/v1/users . If there is any major breaking update, we can name the new set of APIs as v2, v3, or v1.X.X. respectively.