REST API
Have you ever come across a job description like this during your career search?
Responsibilities
- Design, develop, and maintain high-performance back-end services and systems for web and mobile applications.
- Build and integrate RESTful APIs and microservices to support frontend and mobile application functionality.
- ……………
If you have seen requirements like these and felt unsure about what they actually mean, then this article is for you.
REST (Representational State Transfer) is a set of architectural rules and guidelines for designing backend web services. It is not a rigid design pattern or a specific piece of software. Instead, think of REST as a universal design philosophy that teaches your backend and frontend how to talk to each other cleanly over the web using standard internet protocols (HTTP).
Let’s consider an example here.
When you click/tap on the like button on any post in any social media platform, a frontend request to add your like to a backend service send over internet, and this ‘like’ information is then saves in a persistent store, such as database.
But what exactly is happening behind the scenes here? How do the frontend and backend talk to each other so seamlessly? The answer lies in a universal design concept called a REST API.”
Frontend (social media website/app)
POST http://yoursite.com/api/v1/posts/:postId/likes
Here the frontend sends a POST request to backend with post id, the user id will be extracted from the authentication token at backend.
The fundamental rules you should follow are:
1. Use Nouns for Resources (Not Verbs)
URLs should represent things (resources), not actions. Actions belong to the HTTP methods.
- Bad (Verbs): /getUsers, /createNewConversation, /deleteChat / addLike / saveLike
- Good (Nouns): /users, /conversations, /chats, /posts
Frontend Usage Example (Axios):
const res = await axiosinstance.post(`/api/v1/posts/${postId}/likes`);
2. Use Plural Nouns Consistently
Keep your resource names plural across the entire API to avoid confusion about whether you are dealing with a collection or a single item.
- Bad: /conversation, /user
- Good: /conversations, /users
3. Use HTTP Methods for Actions
Let the standard HTTP methods do the heavy lifting for actions (often called CRUD operations).
- GET: Fetch/read a resource (e.g., GET /chats, /posts).
- POST: Create a new resource (e.g., POST /chats).
- PUT: Update an existing resource completely.
- PATCH: Update an existing resource partially.
- DELETE: Remove a resource.
4. Represent Hierarchies with the URL Path
Get SUBEESH PALAMADATHIL’s stories in your inbox
Join Medium for free to get updates from this writer.
Use forward slashes (/) to show relationships between a parent resource and a child resource. Move from the most general category to the most specific.
- Pattern: /parents/parentId/children
- Example: /conversations/5/chats (This explicitly reads as: “Get the chats belonging to conversation number 5”).
5. Use Query Parameters for Filtering and Sorting
Do not change the base URL path to filter, sort, or limit data. Use the query string (anything after the ?).
- Bad: /conversations/active/limit60
- Good: /conversations?status=active&limit=60
6. Use Standard HTTP Status Codes
Always tell the frontend exactly what happened using standard, universal three-digit response codes.
- 200 OK: The request was successful.
- 201 Created: A new resource was successfully created (perfect for POST).
- 400 Bad Request: The client sent invalid data (e.g., missing a required field).
- 404 Not Found: The requested URL or resource does not exist.
- 500 Internal Server Error: The backend crashed or has a bug.
7. Always Communicate in JSON
Both the data sent by the frontend (POST/PUT payloads) and the data returned by your backend should always be formatted as JSON. Ensure your server sends the Content-Type: application/json header.
e.g.,
{
“postId”: “post_123”,
“userId”: “user_456”,
“createdAt”: “2026–08–05T11:23:00Z”,
}
8. Keep URL Casing Consistent
Pick a casing style for your URLs and stick to it everywhere. Kebab-case is the web standard for URLs.
- Inconsistent: /userProfiles (camelCase) and /chat-messages (kebab-case)
- Good: /user-profiles and /chat-messages
9. Include Versioning in the URL
Always prefix your API routes with a version number (like /v1/). This allows you to upgrade your backend code and introduce major changes in the future without breaking the existing frontend application.
- Bad: /api/users (Hard to change later without breaking the app)
- Good: /api/v1/users
Remember, these REST API rules apply universally, regardless of which frameworks or programming languages you choose for your frontend and backend.
