Speaker A
In 2000, Roy Fielding proposed REST as an architectural approach to designing web services.
Explore best practices for designing and implementing REST APIs, covering naming, versioning, filtering, pagination, idempotency, async operations, and more.
Key Takeaways
- Proper REST API design prevents architectural issues and improves developer experience.
- Naming conventions and versioning are critical for maintainability and backward compatibility.
- Filtering, pagination, and sorting optimize data retrieval and performance.
- Idempotency is essential to avoid unintended side effects in repeated requests.
- Asynchronous processing and partial responses enhance API responsiveness and scalability.
Summary
- REST was proposed by Roy Fielding in 2000 and is the standard for web service design.
- Effective API design should be easy to use, hard to misuse, and both complete and concise.
- Use nouns (pluralized) for resource naming and logical grouping in endpoints, avoiding verbs and deep URL nesting.
- Version your API properly to avoid breaking existing clients, either via URL path or query parameters.
- HATEOAS allows navigation of resources via hyperlinks in responses but lacks widespread adoption.
- Implement filtering, pagination, and sorting with query parameters to improve performance and usability.
- Ensure idempotency in API operations to prevent unintended side effects from repeated requests.
- Use asynchronous operations with HTTP 202 status and status endpoints for long-running requests.
- Support partial responses for large resources to improve response times and handle intermittent connections.
- Avoid exposing database structure directly in API design to enhance security.
Full Transcript — Download SRT & Markdown
Speaker A
Since then, REST APIs became the standard, but designing a REST API is still a challenge that many developers and teams tackle even nowadays.
Speaker A
It's very important to design REST APIs properly beforehand, so that we don't run into architectural problems down the road that can affect the whole infrastructure.
Speaker A
We also take into account commonly accepted conventions, security, performance, and ease of use for API consumers.
Speaker A
And this is exactly what we're going to be diving into in this video.
Speaker A
In general, I would summarize an effective API design with three common characteristics.
Speaker A
An API that is easy to read and work with, hard to misuse, and which is complete and concise.
Speaker A
By taking into account the points above, first we're going to look at one of the important aspects of the API design, which is naming.
Speaker A
When defining an API endpoint, always make sure to use nouns to represent resources, not verbs.
Speaker A
So in this example, we're going to use items and employees instead of create items or, for example, get employees.
Speaker A
Also, when designing endpoints, it makes sense to leverage logical grouping.
Speaker A
That is, if one object can contain another object, you should design the endpoint to reflect that.
Speaker A
It's good practice regardless of whether your data is structured like this in the database.
Speaker A
For example, if we want an endpoint to get the orders for a customer, we should append /orders path to the end of the /customers path.
Speaker A
Also, I would advise avoiding reflecting the database structure with your APIs.
Speaker A
To avoid giving unnecessary information to attackers.
Speaker A
You could also go in the other direction and represent the endpoint from the order back to a customer.
Speaker A
With the URL such as orders/99/customers.
Speaker A
However, extending this model too far can become cumbersome to implement.
Speaker A
A better solution is to provide navigable links to associated resources.
Speaker A
One possible solution is using HATEOAS.
Speaker A
Which we're going to be looking into in a minute.
Speaker A
Besides, when defining the names for your endpoints, use pluralized nouns for resources.
Speaker A
Like items and employees instead of item or employee.
Speaker A
A resource has data and relationships to other resources.
Speaker A
A group of resources is called a collection.
Speaker A
Just keep that in mind.
Speaker A
For example, /orders is a collection of orders, right?
Speaker A
And /orders/99 is a resource with information about a specific order.
Speaker A
One important tip though, try to avoid having complex URLs than collection/resource/collection.
Speaker A
Don't go deeper than that.
Speaker A
Also, as a general rule, use hyphens to improve the readability of URLs.
Speaker A
For example, inventory-management instead of the underscore.
Speaker A
Also, don't forget to properly version your API.
Speaker A
Why?
Speaker A
Well, imagine thousands of customers are already using your API and their applications are relying on it.
Speaker A
What if you change one little detail in the URL name or in the response?
Speaker A
Well, then all of these thousands of applications are going to start breaking.
Speaker A
This is not good.
Speaker A
Luckily, you can always easily add a version path to your endpoints, for example, V1/store and so on.
Speaker A
Alternatively, rather than providing multiple versions of URL, you can specify the version of the resource by using a parameter within the query string appended to the HTTP request.
Speaker A
For example, version equals 2.
Speaker A
In the previous point, we mentioned HATEOAS.
Speaker A
HATEOAS makes it possible to navigate all resources without prior knowledge of the URI scheme.
Speaker A
Each HTTP GET request returns information necessary to find resources related to the requested object through hyperlinks included in the response.
Speaker A
The response also includes information that describes operations available on each resource.
Speaker A
For example, to handle the relationship between an order and a customer, the representation of an order could include links that identify the available operations for the customer of the order.
Speaker A
Currently, there are no general-purpose standards that would define the proper usage of HATEOAS.
Speaker A
It's rather just there.
Speaker A
And you wouldn't stumble upon it very often.
Speaker A
So, it's just good to know that this thing exists.
Speaker A
In case if you ever need it in the future.
Speaker A
Our next point is crucial to have in every API.
Speaker A
The databases behind the REST APIs can get very large.
Speaker A
So, we shouldn't assume that we're able to return all of that information in one go.
Speaker A
Therefore, we need ways to filter items by supplying query parameters with specific key-value pairs.
Speaker A
Like last name, value, and age value.
Speaker A
You can extend this approach to limit the fields returned for each item if each item contains a large amount of data.
Speaker A
Similar to how you wouldn't want to fetch all columns of the database.
Speaker A
For example, you could use a query string parameter that accepts a comma-delimited list of fields.
Speaker A
Such as project ID or quantity.
Speaker A
Obviously, we also want to have a way to paginate our data.
Speaker A
Meaning, request specific chunks at one time.
Speaker A
Not to bring our database or services down by requesting all the data.
Speaker A
Meaning, we can accept the limit query parameter and return a number of results that was specified.
Speaker A
In order to paginate the results, meaning receive the next chunk, the user will have to supply an updated value for the start alongside the limit.
Speaker A
Filtering and pagination obviously increase the performance of our queries.
Speaker A
So, it's always good to keep those in mind.
Speaker A
Additionally, we can also allow specifying the fields to sort by in query strings.
Speaker A
For instance, we can get the parameter from a query string with the fields that we want to sort the data for.
Speaker A
Then we can sort them by those individual fields.
Speaker A
For example, +author or -datepublished.
Speaker A
Keep in mind that some older web browsers and web proxies will not cache responses for requests that include a query string in the URI.
Speaker A
One important rule that many developers miss is idempotency.
Speaker A
There's an interesting video covering the case of Uber Eats and how the customers were able to order pretty much unlimited food by making one of the endpoints non-idempotent.
Speaker A
The code that implements the route controllers should not impose any side effects.
Speaker A
The same request repeated over the same resource should result in the same state.
Speaker A
For example, sending multiple delete requests to the same URL should have the same effect.
Speaker A
Okay?
Speaker A
Also, the HTTP status code in the response messages may differ.
Speaker A
That's totally normal.
Speaker A
The first delete request might return status code 204 (No Content), while a subsequent delete request might return status code 404.
Speaker A
But the processing logic should stay idempotent.
Speaker A
As a tip, make sure your controller methods are pure functions.
Speaker A
Let's talk about async operations.
Speaker A
Sometimes a POST, PUT, PATCH, or DELETE operation might require processing that takes a while to complete.
Speaker A
If you wait for completion before sending a response to the client, it might cause unacceptable latency.
Speaker A
If so, simply consider making the operation asynchronous.
Speaker A
Just return HTTP status code 202 (Accepted) to indicate that the request was accepted for processing, but still ongoing.
Speaker A
You should also expose an endpoint that returns the status of the asynchronous request, so the client can monitor the status by polling the status endpoint.
Speaker A
Also, include the URL of the status endpoint in the Location header of the 202 response.
Speaker A
If the client sends a GET request to this endpoint, the response should contain the current status of the request.
Speaker A
Optionally, it could also include an estimated time to completion or a link to cancel the operation.
Speaker A
If the asynchronous operation creates a new resource, the status endpoint should also return the status code 303 after the operation completes.
Speaker A
In the 303 response, include a Location header that gives the URL of the new resource.
Speaker A
As the product gets more complex, a need for supporting partial responses in your REST API comes up.
Speaker A
Large binary fields, like files or images, may be included in a resource.
Speaker A
To improve response times and overcome issues with intermittent connections, we need to enable the retrieve of these resources in chunks.
Speaker A
To do so, the API should support the Accept-Ranges header for GET requests of large resources.
Speaker A
This header allows partial requests for specific byte ranges of a resource, which can be submitted by the client application.
Speaker A
Also, consider implementing HTTP HEAD requests for those resources.
Speaker A
A HEAD request is similar to a GET request, except that it only returns the HTTP headers that describe the resource with an empty message body.
Speaker A
A client application can issue a HEAD request to determine whether to fetch a resource by using partial GET requests.
Speaker A
The Content-Length header here gives the total size of the resource.
Speaker A
And the Accept-Ranges header indicates that the corresponding GET operation supports partial content.
Speaker A
The client application can use this information to retrieve the image in smaller chunks.
Speaker A
Then the first request fetches the first 200 or 2,500 bytes by using the Range header.
Speaker A
The response message indicates that this is a partial response by returning an HTTP status code 206.
Speaker A
The Content-Length header specifies the actual number of bytes returned in the message body.
Speaker A
And the Content-Range header indicates which part of the resource this is.
Speaker A
A subsequent request from the client application can retrieve the remainder of the resource.
Speaker A
Just very similarly to pagination.
Speaker A
Error handling.
Speaker A
There's no way we can miss this one.
Speaker A
To eliminate the confusion for API users whenever errors occur, we should gracefully handle these exceptions.
Speaker A
And return a proper error response code.
Speaker A
So that it kind of gives a clue to the developer how they can debug this issue.
Speaker A
Error codes need to have messages accompanied with them so that the maintainers have enough information to troubleshoot the issue.
Speaker A
But attackers cannot use the error content to carry out attacks like stealing information or bringing the system down.
Speaker A
Be very precise with the codes that you return.
Speaker A
For example, anytime the body of a successful response is empty, the status code should be 204.
Speaker A
Have you already watched my video on authentication?
Speaker A
If not, I would highly suggest watching it first, but here are the basic milestones that every REST API should consider for the basic security.
Speaker A
First of all, using SSL or TLS encryption, obviously.
Speaker A
Also, a normal user shouldn't be able to access information of another user.
Speaker A
They also shouldn't be able to access data of admins.
Speaker A
We're going to talk about the concept of ACLs in the future videos.
Speaker A
Also, track clients and implement throttling to reduce the chances of DOS attacks.
Speaker A
Last but not least, it's worth mentioning OpenAPI.
Speaker A
Formerly known as Swagger.
Speaker A
Which is an open-source standard for describing, documenting, and visualizing RESTful endpoints.
Speaker A
It allows developers to define the structure, endpoints, request-response formats, and other important details of an API.
Speaker A
So, I would highly suggest using it.
Speaker A
As pretty much every other REST API out there.
Speaker A
I really hope you liked this video and learned something new for yourself today.
Speaker A
And if you did, please don't forget to subscribe to be notified whenever a new video is out.
Speaker A
And I will see you in the next one.
Topics:REST APIAPI designAPI versioningHATEOASpaginationfilteringidempotencyasynchronous operationsAPI best practicessoftware development
