We’re amazed at the number, and quality, of free fonts available today. Designers have an incredible choice of free fonts to choose from. So whether you’re looking for a serif, script, or sans-serif font, today’s collection of the best free fonts for designers has you covered! Utilizing a great-looking font is a key part of…
Do you want to start earning money from your website with through WordPress membership management? There are lots of ways that you can turn your site into an additional revenue stream, but many of these options revolve around one-off payments. You could build an online store, sell advertising space, or fill your website with affiliate links—or you could sell…
Add a full-featured and easy-to-implement jQuery image slider to your website to help you keep the attention of your website traffic. CodeCanyon offers some of the best jQuery image sliders available on the web for a one-time low payment. Slider Revolution is one of the best selling jQuery image sliders available on CodeCanyon. Images are…
Facebook, GitHub, Google, and many other giants need a way to serve and consume data. A RESTful API is still one of the best choices in today’s dev landscape to serve and consume data.But have you ever considered learning about industry standards? What are the best practices for designing a RESTful API? In theory, anyone can quickly spin up a data API in less than five minutes — whether it be Node.js, Golang, or Python.
We’ll explore 13 best practices you should consider when building a RESTful API. But first, let’s clarify a RESTful API quickly.
What is a RESTful API?
A RESTful API needs to meet the following constraints for it to be called a RESTful API.
Client-server: A RESTful API follows the client-server model where the server serves data and clients connect to the server to consume data. The interaction between client and server occurs through HTTP(S) requests that transfer the requested data.
Stateless: More importantly, a RESTful API should be stateless. Each request is treated as a standalone request. The server should not keep track of any internal state that might influence the result of future requests.
Uniform interface: Lastly, uniformity defines how the client and server interact. RESTful APIs define best practices for naming resources but define fixed HTTP operations that allow you to modify/interact with resources. The following HTTP operations can be accessed in RESTful APIs:
GET request: retrieve a resource
POST request: create a resource or send information to the API
PUT request: create or replace a resource
PATCH request: update an existing resource
DELETE request: delete a resource
With this deeper understanding of the characteristics of a RESTful API, it’s time to learn more about RESTful API best practices.
Best Practices For Designing Your First RESTful API
This article presents you with an actionable list of 13 best practices. Let’s explore!
1. Use HTTP methods correctly
We’ve already discussed the possible HTTP methods you can use to modify resources: GET, POST, PUT, PATCH, and DELETE.
Still, many developers tend to abuse GET and POST, or PUT and PATCH. Often, we see developers use a POST request to retrieve data. Furthermore, we see developers use a PUT request which replaces the resource while they only wanted to update a single field for that resource.
Make sure to use the correct HTTP method as this will add a lot of confusion for developers using your RESTful API. It’s better to stick to the intended guidelines.
2. Naming conventions
Understanding the RESTful API naming conventions will help you a lot with designing your API in an organized manner. Design a RESTful API according to the resources you serve.
For example, your API manages authors and books (yes, a classic example). Now, we want to add a new author or access an author with ID 3. You could design the following routes to serve this purpose:
Imagine an API that hosts many resources that each have many properties. The list of possible endpoints will become endless and not very user-friendly. So we need a more organized and standardized way of designing API endpoints.
RESTful API best practices describe that an endpoint should start with the resource name, while the HTTP operation describes the action. Now we get:
What if we want to access all books author with ID 3 has ever written? Also for this case, RESTful APIs have a solution:
Lastly, what if you want to delete a book with ID 5 for an author with ID 3. Again, let’s follow the same structured approach to form the following endpoint:
In short, make use of HTTP operations and the structured way of resource mapping to form a readable and understandable endpoint path. The big advantage of this approach is that every developer understands how RESTful APIs are designed and they can immediately use the API without having to read your documentation on each endpoint.
3. Use plural resources
Resources should always use their plural form. Why? Imagine you want to retrieve all authors. Therefore, you would call the following endpoint: GET api.com/authors.
When you read the request, you can’t tell if the API response will contain only one or all authors. For that reason, API endpoints should use plural resources.
4. Correct use of status codes
Status codes aren’t here just for fun. They have a clear purpose. A status code notifies the client about the success of its request.
The most common status code categories include:
200 (OK): The request has been successfully handled and completed.
201 (Created): Indicates the successful creation of a resource.
400 (Bad Request): Represents a client-side error. That is, the request has been malformed or missing request parameters.
401 (Unauthorized): You tried accessing a resource for which you don’t have permission.
404 (Not Found): The requested resource doesn’t exist.
500 (Internal Server Error): Whenever the server raises an exception during the request execution.
A full list of status codes can be found at Mozilla Developers. Don’t forget to check out the “I’m a teapot” status code (418).
5. Follow casing conventions
Most commonly, a RESTful API serves JSON data. Therefore, the camelCase casing convention should be practiced. However, different programming languages use different naming conventions.
6. How to handle searching, pagination, filtering, and sorting
Actions such as searching, pagination, filtering, and sorting don’t represent separate endpoints. These actions can be accomplished through the use of query parameters that are provided with the API request.
For example, let’s retrieve all authors sorted by name in ascending order. Your API request should look like this: api.com/authors?sort=name_asc.
Furthermore, I want to retrieve an author with the name ‘Michiel’. The request looks like this api.com/authors?search=Michiel.
Luckily, many API projects come with built-in searching, pagination, filtering, and sorting capabilities. This will save you a lot of time.
7. API versioning
I don’t see this very often, but it’s a best practice to version your API. It’s an effective way of communicating breaking changes to your users.
Frequently, the version number of the API is incorporated in the API URL, like this: api.com/v1/authors/3/books.
HTTP headers allow a client to send additional information with their request. For example, the Authorization header is commonly used for sending authentication data to access the API.
A full list of all possible HTTP headers can be found here.
9. Rate Limiting
Rate limiting is an interesting approach to control the number of requests per client. These are the possible rate limiting headers your server can return:
X-Rate-Limit-Limit: Tells the number of requests a client can send within a specified time interval.
X-Rate-Limit-Remaining: Tells how many requests the client can still send within the current time interval.
X-Rate-Limit-Reset: Tells the client when the rate limit will reset.
10. Meaningful error handling
In case something goes wrong, it’s important that you provide a meaningful error message to the developer. For example, the Twilio API returns the following error format:
“message”: “Resource books does not exist”,
In this example, the server returns the status code and a human-readable message. Further, an internal error code is also returned for the developer to look up the specific error. This allows the developer to quickly look up more information about the error.
11. Choose the right API framework
Many frameworks exist for different programming languages. It’s important to pick a framework that supports the RESTful API best practices.
For Node.js, back-end developers love to use Express.js, whereas for Python, Falcon is a great option.
12. Document your API
Lastly, write documentation! I’m not joking; it’s still one of the easiest ways to transfer knowledge about your newly developed API.
Although your API follows all best practices outlined for RESTful APIs, it’s still worth your time to document various elements such as the resources your API handles or what rate limits apply to your server.
Think about your fellow developers. Documentation drastically reduces the time needed to learn about your API.
13. Keep it simple!
Don’t overcomplicate your API and keep resources simple. A proper definition of the different resources your API handles will help you to avoid resource-related problems in the future. Define your resources, but also accurately define its properties and the relationships between resources. This way, there’s no room for dispute on how to connect the different resources.
If you liked this article explaining API best practices, you might also enjoy learning about building a RESTful API from scratch.
Crafting an attractive intro is the toughest part of making a video. However, if you’re using Final Cut Pro, you can now skip all that work and get your video made within half the time. All thanks to Final Cut Pro intro templates. The opening scene or the intro of a video needs to be…
Even expert designers and video editors need a helping hand sometimes. In this collection, we’re featuring some of the best After Effects intro templates for quickly making modern and effective intro scenes, logo reveals, and openers for all kinds of videos. These templates can also be easily customized to your preference by changing colors, fonts,…
Tame chaos and transform your content. If you want to showcase your content—posts, images, videos, audio files, and anything else you can think of—into an engaging experience for your website visitors, this article will help you do just that. In this post, I’ll review the 17 best WordPress gallery plugins available on CodeCanyon. I’ll also point…
I currently have nicolas-duclos.com which is my name Nicolas Duclos. However, I’m looking for help to improve the domain name related to what I’m doing which is photography and travel blog.
Nicolas Duclos may be good enough, but I feel like it will not evolve great if I meet someone who wish to also share travel in the future. We can’t be a couple under one name, but I also feel like a random name may look unprofessional when looking for a job as a photographer or marketing.
Here are some ideas from my brainstorming, but I need some advices about if I have good reason to get new domain or I’m just stupid and asking too much on myself.
Social media account
Nicolas Duclos – Travel & Photography
nicolasduclos.com (need to buy from dealer)
Nicolas Duclos (a bit plain)
nicolasduclos.co (maybe better because no “-“?)
Nico Duclos / Nicolas Duclos
niclos.com (for NIColas and duCLOS)
Niclos (A bit weird)
Nic Travel (Look like Travel agency)
Nic the traveller
I’m thinking that my name may be good as a start, but I read somewhere that it’s not recommended to change name afterward if I decide to sell stuffs with other text than my name. Also my name is not spelling good in English which is also why I wanted to choose something else. Do you think it will be a problem for foreigner to have a very French name or people will just call me Nic?
That’s the only thing I need to figure out before I start creating content, because I don’t want to change name each month.
Thank you for your help and advices concerning choosing a good name.
I asked on a lot of subreddit and Facebook group already, but nobody seem to care about that.
“10 good tips to keep in mind when choosing a new template for your self-hosted WordPress installation, from adaptive design, design options, and the most advanced tools.“ Hello! How are you? Starting your new website in your own WordPress? Well! We’re going to try to help you choose the right template for your website…