Guide to RESTful API design best practices in 2026 covering resource-based architecture, stateless communication, client-server separation, URI design, HTTP...
This guide covers essential practices for designing robust, scalable RESTful APIs in 2024:
• Resource-based architecture • Stateless communication • Client-server separation • Uniform interface • Proper URI design • Correct HTTP method usage • Effective request/response handling • Security and access control • Performance optimization • Documentation and versioning • Testing and monitoring
Key recommendations:
- Use clear, noun-based resource names
- Implement OAuth 2.0 and rate limiting
- Cache data and compress responses
- Provide interactive docs with OpenAPI
- Use semantic versioning
- Conduct thorough unit, integration and security testing
- Monitor API health, usage and performance
Best Practice
Description
Resource naming
Use plural nouns (e.g. /users)
HTTP methods
GET (read), POST (create), PUT (update), DELETE (remove)
Authentication
Implement OAuth 2.0 or JWT
Versioning
Use semantic versioning (e.g. v1.2.3)
Documentation
Provide OpenAPI/Swagger docs
Security
Use HTTPS, input validation, CORS
Performance
Implement caching, compression, async processing
Following these practices helps create APIs that are easy to use, maintain and scale.
Related video from YouTube
What changed since this guide was written
REST fundamentals are durable, but the tooling and standards landscape has moved since this was published. OpenAPI 3.1 is now the clear default across most toolchains — it closes the JSON Schema compatibility gap from 3.0 and is what most generators, validators, and doc platforms target today. The API design conversation has also broadened: tRPC has grown significantly in TypeScript-heavy stacks, and the REST-vs-GraphQL-vs-tRPC decision is now a real architectural question teams face early in a project. The core principles in this guide hold; cross-check the tooling recommendations.
Key principles of RESTful API design
Resource-based architecture
RESTful APIs use resources as their main building blocks. A resource is any data or object that can be changed or used. Each resource has its own web address (URI). This lets users access and change resources using basic web methods.
Example Resource
URI
Products
/products
Customers
/customers
Orders
/orders
Stateless communication
In RESTful APIs, each request must have all the info needed to complete it. The server doesn't keep any client info between requests.
This makes RESTful APIs easy to grow and change. Servers can be added or removed without affecting the whole system.
Client-server separation
RESTful APIs keep clients and servers separate. Each has its own job:
Role
Job
Client
Makes requests to the server
Server
Processes requests and sends back responses
This split lets clients and servers be built and fixed separately.
Uniform interface
RESTful APIs use the same set of web methods for all resources. This makes it easy for clients to use the API.
Method
Use
GET
Fetch data
POST
Create new data
PUT
Update existing data
DELETE
Remove data
Layered system
RESTful APIs are built in layers. Each layer does a specific job. This makes the API flexible and easy to grow.
Layer
Job
Presentation
Shows data to users
Business Logic
Handles main tasks
Data Access
Manages data storage
Code on demand (optional)
This optional feature lets clients ask for code from the server to run on their side. It can be useful for complex tasks, but it's not required and should be used carefully to avoid security issues.
How to design good URIs
When making URIs for your RESTful API, follow these tips to make your API easy to use and grow:
Naming resources
Use clear nouns for resource names:
Good Examples
Bad Examples
/products
/getProducts
/customers
/cust
/orders
/order-info
Don't use verbs or short forms in names.
Structuring URIs for relationships
Show how resources are linked:
Relationship
URI Example
Product orders
/products/{product_id}/orders
Customer addresses
/customers/{customer_id}/addresses
This helps users understand how things connect.
Using query parameters
Use query parameters to change what data you get back:
Purpose
Example
Filter
/products?category=electronics
Sort
/products?price=desc
Limit results
/orders?status=pending&limit=10
Don't use query parameters for must-have info.
API versioning methods
Keep your API working for old users when you make changes. Here are ways to do it:
Method
Example
How it works
URI versioning
/v1/products
Put version in the URI
Query parameter
/products?version=1
Add version as a query
Header
API-Version: 1
Use a special header
Pick the way that fits your API and users best.
Using HTTP methods correctly
When making a RESTful API, it's important to use HTTP methods the right way for CRUD (Create, Read, Update, Delete) tasks. Here's a simple guide to the main HTTP methods:
GET: Fetching data
GET is for getting data from the server. It doesn't change anything. The request is empty, and the response has the data you asked for.
HTTP Method
CRUD Task
Request
Response
GET
Read
Empty
Data you asked for
POST: Creating new resources
POST is for making new data on the server. You send the new data, and the server sends back the created data with its ID.
HTTP Method
CRUD Task
Request
Response
POST
Create
New data
Created data with ID
PUT: Full resource updates
PUT is for changing all of an existing resource. You send the whole updated resource, and the server sends back the changed resource.
HTTP Method
CRUD Task
Request
Response
PUT
Update/Replace
Full updated data
Updated data
DELETE: Removing resources
DELETE is for getting rid of a resource. You don't send any data, and the server usually just tells you if it worked.
HTTP Method
CRUD Task
Request
Response
DELETE
Delete
Empty
Success message
PATCH: Partial updates
PATCH is for changing part of a resource. You only send the parts you want to change, and the server sends back the updated resource.
HTTP Method
CRUD Task
Request
Response
PATCH
Update/Modify
Changed parts
Updated data
HEAD and OPTIONS: Getting metadata
HEAD and OPTIONS are for getting info about a resource without getting the resource itself. HEAD gives you headers, and OPTIONS tells you what methods you can use.
HTTP Method
CRUD Task
Request
Response
HEAD
Get info
Empty
Headers
OPTIONS
Get allowed methods
Empty
Allowed methods
Managing requests and responses
When making a RESTful API, handling requests and responses well is key for good communication between the client and server. Let's look at the main parts of managing requests and responses.
Content Negotiation Basics
Content negotiation lets clients and servers agree on the format of the response. This helps when a resource can be shown in different ways, like JSON, XML, or CSV. Clients can ask for what they want, and the server can give it to them.
Here's how it works:
Step
Action
Example
- Client request
Client asks for a specific format
GET /users HTTP/1.1Accept: application/json
- Server response
Server sends data in that format
HTTP/1.1 200 OKContent-Type: application/json
Choosing the Right HTTP Status Codes
HTTP status codes tell clients how their request went. Using the right code helps clients understand and act on the response.
Common status codes:
Code
Meaning
When to use
200 OK
Request worked
When the request succeeds
400 Bad Request
Request was wrong
When the client sends bad data
404 Not Found
Can't find what was asked for
When a resource doesn't exist
500 Internal Server Error
Server had a problem
When something goes wrong on the server
Handling Errors Consistently
Good error handling helps clients understand and fix problems. Here's how to handle errors well:
- Use standard HTTP status codes
- Give a clear error message
- Include error details like codes or IDs
- Use the same error format everywhere in the API
Implementing Pagination and Filtering
As APIs grow, they return more data. Pagination and filtering help manage this by:
- Reducing how much data is sent at once
- Making it easier to find specific information
Here's how to do it:
Feature
How to implement
Example
Pagination
Use query parameters
/users?page=2&limit=10
Filtering
Let clients specify what they want
/products?category=electronics
Metadata
Give extra info about the results
Include total count or page size
API security and access control
Keeping your API safe and controlling who can use it are key parts of making a good RESTful API. Let's look at the main ways to do this.
Setting up OAuth 2.0
OAuth 2.0 is a common way to let users safely share their info without giving out passwords. Here's how to set it up:
Step
Action
1
Sign up your app with an auth server
2
Get a client ID and secret
3
Send users to the auth server to log in
4
Get a token to use the API
Using JSON Web Tokens (JWT)
JWTs are a safe way to send info between systems. They help check if a user can use your API. A JWT has three parts:
Part
Purpose
Header
Tells how the token works
Payload
Has the user info
Signature
Makes sure the token is real
To use JWTs:
- Make a token for each user
- Put the token in API requests
- Check the token when you get a request
API keys and rate limits
API keys show who's using your API. Rate limits stop people from using it too much. Here's what to do:
Task
How to do it
Make API keys
Give each user their own key
Set rate limits
Decide how much each user can do
Watch usage
Keep track of how much people use the API
Role-Based Access Control (RBAC)
RBAC lets you control what different users can do. It works like this:
Step
Action
1
Make roles (like "admin" or "user")
2
Decide what each role can do
3
Give users roles
4
Check roles when people use the API
This way, you can easily manage who can do what with your API.
Improving API performance
Making your API work better is key for happy users, lower costs, and easier growth. Here's how to do it:
Effective caching
Caching stores often-used data nearby, so you don't have to get it from far away each time. This makes your API faster and uses less server power. There are two main types:
Type
Description
Client-side caching
Stores data on the user's device
Server-side caching
Stores data on the server
Use HTTP headers like Cache-Control and ETag to control how caching works.
Data compression methods
Squeezing data makes it smaller, so it moves faster over the internet. This leads to quicker API responses. Here are some ways to do it:
Method
How it works
Gzip
Common compression method
Brotli
Newer, often better than Gzip
Deflate
Another option for compression
Use the Content-Encoding HTTP header to tell which method you're using.
Asynchronous processing
This lets your API handle many tasks at once, making it faster and more responsive. You can do this by:
- Using programming languages that work this way, like Node.js
- Using message queues like RabbitMQ to handle tasks one by one
Handling batch operations
Batch operations let you do many things in one API call. This means fewer calls and better speed. Here's an example:
POST /product-import
[
{
"name": "Cool Gadget",
"price": "$ 12.45 USD"
},
{
"name": "Very cool Gadget",
"price": "$ 19.99 USD"
},
...
]
This API call adds many products at once. The response can tell you how it went for each product.
Benefit
Description
Fewer calls
One call instead of many
Faster overall
Less back-and-forth with the server
Less server load
Server does one big task instead of many small ones
sbb-itb-bfaad5b
Keeping APIs secure
Making APIs safe is key to protect important data and stop people who shouldn't use them. Here's how to make your API safer:
Setting up HTTPS
HTTPS keeps data safe when it moves between users and the API. It stops others from seeing or changing the data. Always use TLS to keep API traffic safe.
Why use HTTPS
What it does
Keeps data secret
Stops others from seeing data
Checks who's who
Makes sure the API server is real
Keeps data the same
Makes sure no one changed the data
Checking and cleaning what users send
Check all data that users send to stop attacks. Do these checks:
- Make sure it's the right type of data
- Check if it's too long or short
- Make sure it's in the right format
- Remove any odd characters
Here's an example in Python:
def check_username(username):
if not isinstance(username, str):
raise ValueError("Username must be text")
if len(username) < 3 or len(username) > 20:
raise ValueError("Username must be 3 to 20 letters long")
if not username.isalnum():
raise ValueError("Username must be letters and numbers only")
return username.strip()
Setting up CORS
CORS controls which websites can use your API. It helps stop some types of attacks. Set these CORS rules:
- Which websites can use the API
- What the API can do
- What info can be in requests
- How long to remember these rules
Here's how to set up CORS in Node.js:
const cors = require('cors');
app.use(cors({
origin: 'https://okwebsite.com',
methods: ['GET', 'POST', 'PUT', 'DELETE'],
allowedHeaders: ['Content-Type', 'Authorization']
}));
Stopping common safety problems
Fix these common issues to make your API safer:
- Limit how much people can use the API
- Use OAuth 2.0 or JWT to check who can use what
- Don't show secret info when there's an error
- Keep all parts of the API up to date
- Watch for and fix problems quickly
What to do
Why it helps
Limit API use
Stops people from using too much
Use OAuth 2.0 / JWT
Makes sure only the right people use things
Be careful with errors
Keeps secrets safe
Update often
Fixes known problems
Watch for issues
Helps you fix problems fast
Creating good API documentation
Good API documentation helps developers use your API correctly. It can make more people want to use your API and have a better time with it. Here's how to make good API documentation:
Using OpenAPI (Swagger)
⚠️ This section was written when OpenAPI 3.0 was the current standard. OpenAPI 3.1 is now the default in most toolchains — it aligns fully with JSON Schema draft 2020-12, which changes how schemas are written and validated. If you are starting a new API project, target 3.1 from the beginning; migrating from 3.0 to 3.1 later requires schema syntax changes.
OpenAPI (once called Swagger) is a way to describe RESTful APIs. It lets you write down:
- What your API does
- How to use it
- What it needs to work
This makes it easy for developers to understand your API. With OpenAPI, you can make:
- Documentation that developers can try out
- Code that works with your API
- Basic server code
Making interactive API docs
Interactive API docs let developers try your API without writing code. Tools like Swagger UI and ReDocly can make these docs from your OpenAPI file. With these, developers can:
- Look at your API
- Send test requests
- See how the API responds
Providing code examples and SDKs
Code examples and SDKs help developers start using your API quickly. Here's why they're useful:
Item
Purpose
Code examples
Show how to use the API in different coding languages
SDKs
Give ready-made tools to work with the API
By giving both, you help more developers use your API easily.
Keeping a clear changelog
A changelog tells developers what's new or different in your API. It's important because it:
- Shows what's new
- Tells what has changed
- Warns about old parts that might stop working
Managing API versions and changes
Keeping your API up-to-date while not breaking existing apps is key. Here's how to do it well:
Using semantic versioning
Semantic versioning uses three numbers (like 1.2.3) to show how big a change is:
Number
Meaning
Example
First
Big changes
2.0.0
Second
New features
1.3.0
Third
Small fixes
1.2.1
This helps developers know if an update will work with their app.
Keeping old versions working
To make sure old apps still work:
- Use default values for new things
- Let apps choose which data format they want
- Tell developers clearly about changes
How to remove old API parts
When you need to remove old parts of your API:
- Tell users early
- Give tools to help move to the new version
- Explain when the old part will stop working and how to update
Dealing with big API changes
For big changes:
- Plan ahead
- Pick a way to show versions that fits your API
- Keep old versions working if you can
- Test a lot
- Write down how your API works and changes
Step
What to do
Plan
Think about future changes
Choose
Pick how to show API versions
Keep working
Make sure old apps still work
Test
Check everything works right
Write
Explain how the API works and changes
Tracking API performance and use
Keeping an eye on how your API works and how people use it helps make sure it runs well. Here's what you need to do:
Setting up good logging
Good logs help you find and fix problems. They also show how people use your API. Your logs should have:
- Details about API requests and responses
- Information on errors and warnings
This helps you understand what's happening with your API.
Measuring API performance
Checking how fast your API works is important. You should look at:
Metric
What it means
Response time
How long it takes to answer a request
Latency
Delay in the system
Throughput
How many requests the API can handle
Use tools that watch APIs to get this information.
Analyzing API usage
Looking at how people use your API helps you make it better. Keep track of:
- How many API requests you get
- Which parts of the API people use most
- Who is using your API
This info helps you decide what to improve.
Monitoring API health and uptime
Making sure your API is always working is key. Watch for:
Thing to check
Why it's important
Uptime
How long the API stays working
Downtime
When the API stops working
Response codes
Shows if the API is answering correctly
Use tools that check on your API to spot problems quickly.
Testing RESTful APIs
Testing your API helps make sure it works well, stays safe, and runs fast. Here are the main types of tests you should do:
Writing unit tests
Unit tests check small parts of your API, like single functions or endpoints. They help find problems early. When making unit tests:
- Test both normal and unusual inputs
- Check how your API handles errors
- Look at edge cases (very big or small numbers, empty lists, etc.)
Performing integration tests
Integration tests make sure different parts of your API work well together. They copy real-world use. These tests:
- Take more time than unit tests
- Check how your whole API works, not just small parts
- Help find problems that only show up when parts work together
Conducting load tests
Load tests see how your API handles lots of users or data. They help you:
Goal
How it helps
Find slow spots
Shows where your API slows down
Use resources better
Helps your API run faster
Handle sudden busy times
Makes sure your API works when lots of people use it at once
You can use tools like JMeter or Gatling for these tests.
Running security tests
Security tests look for ways someone could break into your API. They help keep your data safe. You can do these tests:
Test type
What it does
By hand
You try to break the API yourself
With tools
Use programs like OWASP ZAP or Burp Suite to find problems
These tests look for common problems like:
- SQL injection (putting bad code in database queries)
- Cross-site scripting (XSS) (putting bad code on web pages)
- Ways to get around login checks
Advanced API concepts
Understanding HATEOAS
HATEOAS helps APIs work better by using links. It lets clients find their way through the API without knowing all the details beforehand. Here's how it works:
Feature
Description
Links in responses
API sends links to related resources
Client navigation
Clients use links to move through the API
Flexibility
API can change without breaking client apps
To use HATEOAS, put links in your API responses. This shows clients what they can do next.
Using WebHooks for events
WebHooks let APIs tell clients when something happens. They work like this:
Client gives API a URL to call
When something happens, API calls that URL
Client gets the update right away
This is good for apps that need to know about changes quickly. It's better than having clients check the API all the time.
Combining GraphQL with REST
GraphQL and REST are two ways to make APIs. You can use both to make a better API:
API Type
Good for
GraphQL
Letting clients ask for exactly what they need
REST
Managing data in a simple way
Using both gives clients more choices. They can pick the best way for what they're doing.
APIs in microservices
Microservices are small parts of a big system. APIs help these parts talk to each other. Here's how it works:
Role of APIs
What it does
Connect services
Let different parts of the system work together
Share data
Move information between services
Work independently
Let each service be built and run on its own
When using APIs with microservices, you need to think about:
- How to handle different versions
- Keeping things safe
- Watching how the APIs are working
This helps make sure all the parts of the system work well together.
REST vs tRPC vs GraphQL: when to pick REST in 2026
REST is still the right default for most public APIs and service-to-service communication — but the decision deserves a moment's thought in 2026. GraphQL remains the better choice when clients need flexible, field-level queries across a complex graph of related data (common in content-heavy or dashboard-heavy products). tRPC has taken real market share in TypeScript monorepos: it generates end-to-end type safety without a schema file, so if your frontend and backend are both TypeScript and in the same repo, the boilerplate advantage over REST is real. REST wins when you are building a public API for external consumers, when you want maximum tooling compatibility (OpenAPI generates client SDKs, mock servers, and docs automatically), or when your team is polyglot. The core of this guide applies regardless of which you pick — good resource modeling, correct HTTP semantics, and solid error handling matter everywhere.
Conclusion
Summary of key practices
This guide covers the main ideas for making good RESTful APIs. We talked about:
- How REST works
- Keeping APIs safe
- Using caching to make APIs faster
- Changing APIs without breaking things
These ideas help you make APIs that work well, are easy to fix, and do their job quickly.
What's next for API design
As computers and the internet change, APIs will need to change too. New things like small computer parts working together, smart devices, and computer thinking will affect how we make APIs. To make good APIs in the future, keep learning about new ways to do things.
Final thoughts on API building
Making a good API means knowing how they work and always trying to make them better. If you follow the advice in this guide, you can make APIs that:
API Quality
What it means
Strong
Can handle lots of use
Growable
Can get bigger when needed
Easy to fix
Can be updated without much trouble
Remember these main points:
- Keep things simple
- Make APIs that can change
- Keep APIs safe
- Think about the people using your API
If you do these things, you'll make APIs that work well for your business and make users happy.
FAQs
What are REST API guidelines?
REST API guidelines help you make APIs that work well, are easy to fix, and simple to use. Here are some key things to do:
Guideline
Description
Use JSON
Send and receive data in JSON format
Use nouns in paths
Example: /users instead of /getUsers
Use plural nouns
For collections, like /products
Nest resources
For linked items, like /users/{id}/orders
Handle errors well
Use standard error codes and clear messages
Allow data sorting
Let users filter, sort, and get data in parts
Keep it safe
Use good security practices
What to think about when making a REST API?
When making a REST API, keep these 7 things in mind:
- Name endpoints right
Use clear, consistent names for your API endpoints.
- Use the right HTTP method
Pick GET, POST, PUT, or DELETE based on what the endpoint does.
- Handle requests and responses well
Make sure your API can take in and send out data correctly.
- Use headers for login
Put login info in the request headers, not in the URL.
- Know when to use parameters or query strings
Use parameters for must-have info, query strings for extra details.
- Use caching to make it faster
Store often-used data to speed up your API.
- Write good docs
Make clear, detailed instructions on how to use your API.
