7 Tips to Create Better Rest APIs

Some of the most common mistakes developers make when trying to build a REST API are:

• Poorly written documentation
• Undefined architecture
• Inconsistent endpoints definitions
• Unclear communication
• Weak security measures

We do not live in a perfect world. It’s normal to make mistakes. However, before you get involved in any project, you must take all the precautions and know all the risks or mistakes that you could make.

The same approach applies to our case. That’s why our team will offer you a couple of tips based on their personal & professional experience in the following paragraphs.

Documenting your API helps you and your team understand the application’s data flow better. Inevitably, problems will arise when building an API. Things like library updates, API versioning or security issues will make you wish you had written the documentation.

By managing this, you also decrease the resources spent onboarding new remote or in-house software developers and increase the ease with which the team takes updates and maintenance actions. Try to give them the advantage of building on top of your API even without them fully understanding the technologies you have used.

Thankfully, nowadays, it is much easier to create documentation. Tools like Apiary, Swagger, Raml and many more help developers generate documentation in an instant. You can always take some inspiration from useful, well-written documentation like The Rust Docs, GitHub Developer Docs, Ruby On Rails Guides, CasperJS, or Moment.js.

We should always try to keep the communication between the client and the server private.

Developers use APIs to build their services and transfer data. If an API is broken, exposed, or has major data breaches, it definitely will not be chosen by any developer.

Try to validate request parameters from the beginning. Implement validation checks and block every request that does not pass that specific validation. Include validations for input types, formats, and length. Accept only certain HTTP methods for specific endpoints and include timestamps for your request just so only the ones that are made in a certain timeframe will be accepted. This prevents some of the brute force attacks that will possibly hit your servers.

You can take your authentication security a step further by implementing the OAuth 2.0 authentication framework. With the help of third-party apps, you can create a more secure environment for your users.

Never expose delicate information, like usernames, passwords, API keys, etc., in URLs. If you really need to transfer this information by storing it in the URL, serialize how only the machine you need to communicate with will understand the received data.

The API is like a bridge between the server and the client. This is why we should transfer data in a format suitable for both parties. This choice will influence the speed and success of the requests.

Some of the most frequently used data formats when building an API are direct data, feed data, and database data formats.

Direct data formats are the best option when trying to interact with other APIs. Some of the most commonly used are JSON, YAML, and XML.

Feed data formats are usually used to publish updates from servers or front end web applications and notify users these changes have been made. As you probably already guessed, these formats are most commonly used for social media, blogs, or video-sharing platforms.

In most cases, database data formats are used to manipulate data between different databases or between other applications and databases. SQL and CSV are two of the most frequently used formats in this category.

If the API you and your team are building will return great amounts of data, it might be a good idea to implement pagination. We should always avoid any situation where the user might get the opportunity of bringing down the service.

We recommend using a default limit for the returned data and parameters like limit and offset, just like this: /users?limit=30&offset=60.

Pagination also offers a great opportunity to help your users with decision fatigue and removes the already despised infinite scroll.

The process of versioning an API helps developers maintain control over the application. You can never know how a new update affects the usability of every user. Always try to keep the old versions of your API backed up, even if you change it completely.

Let’s see some examples of how can an API be versioned:

• Place the version number directly in the API’s URL: api.example.com/v1/users
• Set custom headers to include the API’s version number: curl -H “API-version: 1.0” https://api.example.com/users
• Adjust the accept header to include the API’s version number: curl -H “Accept: application/vnd.example.v1+json” https://api.example.com/users
• Add the version number as a query parameter: https://api.example.com/users?version=1

RESTful APIs have four methods of indicating what developers will do with the passed data.

Although it may seem like the logical thing to do, developers tend to use just 2 of the following presented HTTP methods. It’s a perfect practice to use each one of them every time the situation calls for it.

• GET — Use this method every time you need to fetch a resource or a collection of resources.
• POST — Developers should use it every time they need to create a new resource or collection of resources.
• PUT — This method is used for updating specific pieces of information.
• DELETE — It’s pretty self-explanatory. It helps us delete existing resources or the collection of resources.

Just as developers prefer only to use two of the previously mentioned HTTP codes, most of the time, they only use just two HTTP codes. This can bring many headaches to their future selves and to all the developers that will work on the project in the future.

• 200 OK — This is the most common code we stumble upon as developers. Or at least we hope to do so. It’s presented to us whenever an operation has been performed successfully.
• 201 CREATED — The previously presented POST method goes hand in hand with this HTTP code as it’s supposed to alert the client that successfully created the resource.
• 400 BAD REQUEST — This is the HTTP code that will appear whenever a request has not been performed successfully.
• 401 UNAUTHORIZED — If we need to restrict a user’s access to a part of our application, this should be the HTTP code we send along with the error message.
• 404 NOT FOUND — The most common HTTP code on the entire internet. Even people who have not studied software development know the 404 HTTP code means the resources have not been found.
• 500 INTERNAL SERVER ERROR — One should return this error whenever the server fails to respond.

As you can see, all HTTP codes are pretty self-explanatory. Using each one of them when the situation calls for it can help save a lot of time in the long run.

We all know how frustrating it is when we get an error and the message it’s a vague one. Not only is the service not working, but we now have to find where the problem comes from.

We must throw the right error messages and the most explicit HTTP error code to eliminate this confusion.

For example, if a user wants to create a new account but the email is already used on the platform, we should return a 400 HTTP code with the message “Email already exists”. In this way, we avoid dealing with a considerable number of requests because the user will know what the issue is, and will not force the registration.

Here we are at the end of a complete list of tips. These are just some of the methods you can use to create a more secure REST API. Of course, there are many more out there, but if you only use the ones presented above, you will probably be ahead of most ones that are already built.

If, however, you do not have the time and patience to build an API for your web scraping projects, why not invest in something ready-made? Our team made the effort to create one of the most secure and easy-to-use web scraping APIs. These are just some of the main principles they have used to ensure there will never exist any data breaches or API downtime.

If you want to give it a shot, you can get 1000 API calls by creating a free account and testing one of the most successful web scraping APIs.

Start your web scraping journey now!