Designing Pragamtic RESTFul APIs

Pragmatic REST API design is the process of designing a REST API that is easy to use, scalable, and maintainable.

In this article, we are exploring key principles to consider when designing a pragmatic REST API.

Design principles

• API should be simple & easy to understand without having to refer to the documentation.
• API should be intuitive and consistent & easy to adopt
• Design API URLs, Endpoints, API requests, and responses considering the User Interface in mind
• Use standard, generics terms, not business terms or acronyms
• Start with major use cases, evolve API around those use cases iteratively

Uniform Interface

Adhere to the core principles of REST, such as using HTTP methods (GET, POST, PUT, DELETE) and HTTP status codes to provide a consistent and predictable interface for API clients.

URLs

While designing the rest API, deciding URL is a very important part as it’s the entry point to your API.
The key principles of REST involve separating your API into logical resources.

Following are some design rules for URL

• Keep it simple
• this is not the method or class name

Nouns

Use resource-oriented URI structure. Organize your API endpoints around resources, rather than actions, and use nouns to name resources, not verbs.
Don’t follow method driven approach while designing URL, will end up in verbs in the URL

Resource “/orders” instead of “/getOrders” or “/createOrder”

Plurals

Resource Names don’t mix up singular and plural nouns. Keep it simple and use only plural nouns for all resources, the URL format will be consistent across all operations

List Of Orders : /orders
Single Order : /orders/001

Consistent case

Lowercase letters should be preferred in URI paths.
Choose between snake case or camelCase for parameters and attributes but you should remain consistent.

GET /orders?customer_id=001 or GET /orders?customerId=001
POST/orders {“customer_id”:”001″} or POST/orders {“customerId”:”001″}

Example of the Orders API

GET /orders # Retrieves a list of orders
GET /orders/1 # Retrieves a specific order 1
POST /orders # Creates a new order
PUT /orders/1 # Updates order 1
PATCH /orders/1 # Partially updates order 1
DELETE /orders/1 # Deletes order 1