Best REST API Practices and Tools

Web development has changed dramatically in the last few years. Websites are used to use template search engines to provide a page and send it to a client. It used to have a SOAP protocol to get information from another server that often uses XML as its default language. Later, it appeared RESTful and people started using it with JSON. These days, RESTful is something that controls the entire website instead of just the remote parts. Displaying posts, showing a list of posts, user data, and more, all done with RESTful instead of the presentation provided by the server. Below, RESTful is very important these days in web development and other software that needs to connect to the server and get some data, and this value encourages us to use the best pattern and related tools to achieve the best quality and ensure system maintenance.

In my experience of compiling APP, I have encountered many problems I found some details while still in progress. Here I share what I have learned and how to create RESTful APIs and answers to frequently asked questions.

Image for post
Image for post

What is REST?

RESTful is the architectural style of designing a place where software can access data. RESTFul APIs typically retrieve JSON data as it is read in multiple programming languages ​​effortlessly.

Is it possible to retrieve anything other than JSON?

Technically, yes! RESTful is a construction-only pattern and does not directly require you to use JSON. The RESTful API can retrieve plain text, XML, CSV, or any other format but once the community has chosen JSON it is best to continue with that. Many of the tools used to design the RESTful API assume that your endpoints return JSON and nothing else.

How to design a RESTful API server?

The RESTful API server can be built using almost all backup system languages. We will discuss this later in this article. Here we try to understand the RESTful API pattern. What is often needed in the app is CRUD (create, read, update, delete) capability. . These are the four things all apps have. Like creating posts, reading posts, updating posts, and finally deleting posts. In the RESTful API, you will create a path (route) called / post. A typical naming convention uses plurals. As you see CRUD has four methods. thus it needs to assign all the methods. The HTTP protocol has four modes for this issue, namely POST, GET, PUT, DELETE. These methods can be applied sequentially to CRUD action. Here is an example:

GET /posts # Get the posts list
GET /posts/{id} # Get the post with id of {id}
POST /posts # Create post
PUT /posts/{id} # Update the post with id of {id}
DELETE /posts/{id} # Delete the post with id of {id}

The beginning of the route as /post is also often called a collection.

Do not use abbreviated words such as /p for /posts. This makes it difficult to remember what the endpoint does.

Never use verbs in the name of the method. This means that the following routes are not considered RESTful API:

POST /createPost
POST /deletePost
POST /updatePost

HTTP methods are no different when it comes to POST, PUT, and DELETE. But applying POST to all routes makes it confusing.

Why do we need to use plural nouns?

Use singular form can be confusing. Imagine using a route or post but you get all the posts!

Why should we not use the verb in road names?

Use an action in the name of the method will make the final API points much higher than required. But in the case of using HTTP methods on the same route, you have a shorter and easier to understand API.

For example, can we use GET to make a record?
And technically speaking, yes! But it should not be, as the GET method is commonly used to obtain data. And even if you pay attention it makes more sense to “Get that post” to get data for that post instead of calling it “Post that post” to get details of that post.

Nesting

Imagine you have a post and want to get your comment. You can use the nest build method to represent resource items (such as posts) or in sequence mode.

Since you already have a GET route/post/{id} you need to add a set of routes below:

GET /posts/{id}/comments # Get all comments of post with id of {id}
GET /posts/{id}/comments/{cid} # Get the comment with id of {cid} of post with id of {id}
POST /posts/{id}/comments # Send a comment belonging to post with id of {id}
PUT /posts/{id}/comments/{cid} # Update the comment with id of {cid} of post with id of {id}
DELETE /posts/{id}/comments/{cid} # Delete the comment with id of {cid} of post with id of {id}

Querying

You do not always need to get all the posts or all the data from a particular source. Sometimes you need to filter, filter, or clean it. In addition to how you handle this issue in your postcode you should follow some rules to make your endpoint clear:

Use full question name Do not use p to find paginating or f filter.

  • If your query is more than one word, separate them with a drawing line (often called a snake_page). For example, never use limitPerPage or limitperpage, instead, you should use limit_per_page.
  • Never combine two data into one Although some people combine some data, I do not like this behavior at all because it reduces readability. For example, when ordering a day you should use two question frames called order_by and order. For example, the route should be like /posts/?Order_by=date&order =asc instead of /posts/?Order_by=date:asc or /posts/?

Finally, the questionnaire should look like this:

GET /posts/?page=1&limit_per_page=20&order_by=date&order=desc

Instead of this:

GET /posts/?p=1&lpp=20&&o=date:desc

Errors

Whenever a task is done successfully returns a response with a code 200. Whenever a route is not available return a response with a code of 400. Some editors forgot to do this and only mentioned the result in the JSON response instead of the HTTP response itself as well. Retrieving code makes it easier to manage responses. Here is a list of standard HTTP response codes: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

The error should also contain a readable human message and a domain-specific message that your application can only understand for future use. For example, this could be an error message:

HTTP/1.1 403 Forbidden
...
{
"status": 403,
"err_code": "permission_denied",
"message": "User doesn't have enough privileges"
}

An error-free API should not return an error message created by a server or language. In the event of any error be sure to correct it (for example by using a try/catch block) and return the correct JSON response.

Version your API

Over time you may need to change some of your API functionality. This may also violate the applications that use it. So to prevent this problem your API and allow the previous API to exist for a while until you install all previous APIs with the new API. One of the most widely used ways to do this is to attach all the final points of the API and version. For example:

/api/v1/post

What languages/frameworks and database should we use to design a RESTful API server?

As mentioned earlier, the most widely accepted RESTful pattern is not language-specific. So you can create a RESTful API server using your preferred language or framework.

Very common as I write this post the draft of the Express. It is very easy and fast to create a RESTful API using Express. Express is built on top of Node.js so you should know JavaScript to use this framework.

Another option would be Laravel. Laravel provides almost all the required RESTful API assets out of the box, as authentication and routing. Laravel is written in PHP.

The aforementioned frameworks are completely personal. You can continue with any other option. I said this as I tried many options and found it easy and fun to work with.

A database can be a huge issue when writing any application. The RESTful API server is also affected. Your information should be fast and secure. Depending on the needs of your application you must select your database. If you need database-side relationships you should go with RDBMS such as MySQL or PostgreSQL. If you plan to grow your database horizontally it is best to choose MongoDB.

Designing the RESTful API does not need to be done in a single language or framework. The method can be microservices written in multiple languages. You may need more information based on their use or in many programming languages ​​depending on their useful libraries or working in specific situations. This is where microservices can help.

Assume you are assigned to design a photo-sharing API and process the website and you want it to be faster and then select Express / Node.js for your background code. But you know that Python has many good AI libraries or image processing. Here you can use Python as a microservice to help you complete your main API server.

Testing your API server

When designing an API server (either RESTful or not) you need to check it every time you create a new route or make changes to the previous one. It is not possible to reload the browser all the time or create a form using HTML to send data back and forth with custom headers. So all you need is API testing software. There are many tools out there but the one I usually choose to use is Postman. It’s free and easy.

Image for post
Image for post

Postman includes all the feature features you need to test your API, including all HTTP methods, custom titles, parameters, and so on. It prepares the JSON response and provides you with the necessary HTTP request code as explained in multiple languages ​​and in cURL

Written by

🤠 Internet Cowboy | 💻 JS Aficionado | http://imharshpatel.com/

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store