Best practise to define well formed REST API

1 Introduction

REST API is resource-oriented web service. Three key points to define a well-formed API are

  1. URI pattern
  2. HTTP Headers
  3. API Object Definition

Below are the check lists to when design the API.

URI pattern

  1. Use nouns but no verbs
  2. GET method and query parameter should not alter the state
  3. Use plural nouns
  4. Use sub-resources for relations
  5. Provide filtering, sorting, field selection and paging for collection
  6. Version API

A recommended URI pattern is http(s)://{}/{version}/{resources}/{id}/{sub_resources}/{sub_resource_id}

HTTP headers

  1. HTTP verbs POST, GET, PUT/PATCH, and DELETE correspond to create, read, update, and delete (or CRUD) operations, respectively.
  2. Use HTTP headers for serialization formats
  3. Handle Errors with HTTP status code

API Object Definition

  1. Object is self-constraint
  2. Unify collection objects
  3. Unify error object

2 API Examples

Below is an example of car API.

b0f7aae2 642f 477c acdb 4ba07f06868e1

3 Reference

· URI pattern


· HTTP Verb


· API Object definition

Aside | This entry was posted in API, rest, web, Webservice and tagged , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s