DEV Community

george_pollock
george_pollock

Posted on • Originally published at hvitis.dev on

REST API Best practices - Why's and How's

Why your API should be REST ?

REST helps. A lot. Let’s focus on what REST gives your team. The picture I’ve chosen respresents the idea very well. In a crowd of backenders, front-enders, clients, users and testers - well design API increases productivity and efficiency, decreases frustration, let’s people cooperate better. In case you’re a bit confused on what’s REST try improving your knowledge before continuing.

If you are a front end developer you may want to save yourself writing custom messages for bad error requests. You may want to have a reusable functions for services and getting data, this shines when things are consistent. When requests you make are predictible, when their codes represent the actual state.

If you are a back end developer you may want to check your services by calling them while developing. It’s easier to debug if you can actually read in a message what did just happen instead of seeing empty body. Coding is not guessing, requests responses should be self explanatory.

If you are a tester then you should make everybody follow the REST practices, otherwise you will go nuts. Backend API testing tools like POSTMAN could ease your work, especially if you know some tricks. If you want to perform server side automation testing and write set of tests for the API - it will be hard if all you get is unconsistency in HTTP responses. Even if your API testing resume says: automation tester - it only makes sense if the API is well designed.

If you are a user - you have a limited contact with developers, maybe the only thing that could help you is documentation. Well designed API could benefit from rest api documentation tools like SWAGGER, Sphinx or POSTMAN but the best documentation won’t have all the possible error you may encounter when using API. That is why for the sake of the future and potential integrations or exposing your API to customers, please, design well!

How to design well ?

Here is the list of must haves:

Error handling

In order to provide more specific machine-readable messages with an error response, the API clients can react to errors more effectively and eventually it makes the API services much more reliable from the REST API testing perspective. Clients could benefit a lot from a good error handling since they can use the message strings comming directly from backend ( that eases translation issues ).

For non-success conditions, developers SHOULD be able to write one piece of code that handles errors consistently across different Microsoft REST API Guidelines services.

This quote comes from Microsoft’s REST API design best practices (it’s a great place to learn although it often shows design examples of api architecture for a huge project).

The quote says you need a wrapper. Some class or function that will be responsibe for showing a consistant error message for non-success requests. One important reminder: Error responses MUST use standard HTTP status codes in the 400 or 500 range to detail the general category of error.

In case you are developing a huge system then go back and take a look at Microsoft’s example. My take on this for smaller projects would be as follows:

Error : Object
Property Type Required Description
code String ✔ One of a server-defined set of error codes.
target String The target of the error.
message String ✔ A human-readable representation of the error.
details details[] An array of details about specific errors that led to this reported error.
Details : Object
Property Type Required Description
code String ✔ A more specific error code than was provided by the containing error.
target String The target of the error.
message String ✔ A human-readable representation of the error details.

The simple design example example:

{
  "error": {
    "code": "WrongMediaType",
    "message": "Data types accepted: csv, json."
  }
}
Enter fullscreen mode Exit fullscreen mode

(this message should be returned along with status code 413)

Other extended example:

{
  "error": {
    "code": "BadArgument",
    "target": "GetAllCatsService",
    "message": "Data introduced has 1 error.",
    "details": [
      {
        "code": "NullValue",
        "target": "CatWeigth",
        "message": "Cat's weight must not be null"
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

The way you name your key&value pairs in returned object is totally up to you. The way you construct your wrapper is also your choice although you may want to use one of existing libraries.

SUM_UP: Error handling is extremely important for backend automation testing and usability, it also could bring more profits for clients. It is possible to start small with a simple error / message object that could be extended with time and complexity.

Methods

There is many HTTP methods but you should use at least those:

Using methods is strictly connected with naming consistency because the method themselves are verbs which is a direct reason why you should avoid using verbs in your URLs. Instead of duplicating code and making it unmaintainable and unintuitive - use methods well.

GET: https://yourdomain.com/getCats ⬅️🛑Wrong
GET: https://yourdomain.com/cats ⬅️✅ Good

POST: https://yourdomain.com/getCats ⬅️🛑Wrong
GET: https://yourdomain.com/cats ⬅️✅ Good

GET: https://yourdomain.com/getCats ⬅️🛑Wrong
GET: https://yourdomain.com/getCat/{id} ⬅️🛑Wrong
POST: https://yourdomain.com/postCats ⬅️🛑Wrong
DELETE: https://yourdomain.com/deleteCats ⬅️🛑Wrong

GET: https://yourdomain.com/cats ⬅️✅ Good
GET: https://yourdomain.com/cats/{id} ⬅️✅ Good
POST: https://yourdomain.com/cats ⬅️✅ Good
DELETE: https://yourdomain.com/cats ⬅️✅ Good
Enter fullscreen mode Exit fullscreen mode

There is more methods and more ON methods. Read-up before continuing!

Difference between POST/PUT/PATCH

It’s pretty simple:

POST creates a new resource that did not exist before:

POST:
URL: https://yourdomain.com/cats/
REQUEST:

{
  "name": "George",
  "color": "black",
  "is_adopted": true
}

RESPONSE CODE: 201
RESPONSE:

{
  "id": 1,
  "name": "George",
  "color": "black",
  "is_adopted": true
}
Enter fullscreen mode Exit fullscreen mode

PUT updates resource previously created with a new object information:

PUT:
URL: https://yourdomain.com/cats/{catId}
REQUEST:

{
  "name": "Bob",
  "color": "white",
  "is_adopted": false
}

RESPONSE CODE: 200
RESPONSE:

{
  "id": 1,
  "name": "Bob",
  "color": "white",
  "is_adopted": false
}
Enter fullscreen mode Exit fullscreen mode

PATCH updates resource previously created with partial information:

PUT:
URL: https://yourdomain.com/cats/{catId}
REQUEST:

{
  "name": "Zoey"
}

RESPONSE CODE: 200
RESPONSE:

{
  "id": 1,
  "name": "Zoey",
  "color": "white",
  "is_adopted": false
}
Enter fullscreen mode Exit fullscreen mode

Naming consistency

It’s simple:

  • URIs resources as nouns - do not use verbs in your URI 
GET: domain.com/getCats ⬅️🛑Wrong
GET: domain.com/getCat/{id} ⬅️🛑Wrong
POST: domain.com/postCats ⬅️🛑Wrong
DELETE: domain.com/deleteCats ⬅️🛑Wrong

GET: domain.com/cats ⬅️✅ Good
GET: domain.com/cats/{id} ⬅️✅ Good
POST: domain.com/cats ⬅️✅ Good
DELETE: domain.com/cats ⬅️✅ Good
Enter fullscreen mode Exit fullscreen mode
  • Pluralized resources 
GET: domain.com/cat ⬅️🛑Wrong
GET: domain.com/cat/{id} ⬅️🛑Wrong

GET: domain.com/cats ⬅️✅ Good
GET: domain.com/cats/{id} ⬅️✅ Good
Enter fullscreen mode Exit fullscreen mode
  • Lowercase letters and dashes 
GET: domain.com/Cats ⬅️🛑Wrong

GET: domain.com/cats ⬅️✅ Good

---

GET: domain.com/cat_races ⬅️🛑Wrong

GET: domain.com/cat-races ⬅️✅ Good
Enter fullscreen mode Exit fullscreen mode
  • (American) English 
GET: domain.com/gatos ⬅️🛑Wrong

GET: domain.com/cats ⬅️✅ Good
Enter fullscreen mode Exit fullscreen mode
  • No file extensions 
GET: domain.com/cats.pdf ⬅️🛑Wrong

GET: domain.com/cats ⬅️✅ Good
Enter fullscreen mode Exit fullscreen mode
  • Do not use trailing slashes 
GET: domain.com/cats/ ⬅️🛑Wrong

GET: domain.com/cats ⬅️✅ Good
Enter fullscreen mode Exit fullscreen mode
  • Snake_casing for query parameters 
GET: domain.com/cats?skinColor=black ⬅️🛑Wrong

GET: domain.com/cats?skin_color=black ⬅️✅ Good
Enter fullscreen mode Exit fullscreen mode

Resources

  • They should be flat, no nesting. 
GET: domain.com/animals/{id}/family/{id}/colors/{id}/cats ⬅️🛑Wrong

GET: domain.com/cats ⬅️✅ Good
Enter fullscreen mode Exit fullscreen mode
  • If nested is required it should be shallow. 
GET: domain.com/animals/{id}/family/{id}/colors/{id}/cats ⬅️🛑Wrong

GET: domain.com/animals/{id}/cats ⬅️✅ Good
Enter fullscreen mode Exit fullscreen mode

Returning objects

It depends on your client and architecture but in most cases it’s good to return a body on creating resources.

{
  "result": {
    "cat": {
      "id": 1,
      "name": "Georgina"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

You could think about wrapping the responses with additional info but you need to remember that certain requests should return empty body e.g. DELETE requests. Once the resource has been deleted and status code 204 returned then body should be empty. In most cases the decision on body of successful requests is up to you or your front-end collegue.

Slash redirect

As part of naming consistency: do not use trailing forward slashes. In case of using slashes e.g. by your users (mistakes / no docs etc) you should try to redirect to original resource. It’s an interesting topic, try reading more about it.

“The trailing slash must not have specific semantics. Resource paths must deliver the same results whether they have the trailing slash or not.” - Zalando’s RESTful API guidelines

Status codes

Like with HTTP methods there is many of them. Try starting from the basics:

  • 200s 
HTTP_200_OK
HTTP_201_CREATED
HTTP_204_NO_CONTENT
Enter fullscreen mode Exit fullscreen mode
  • 300s 
HTTP_301_MOVED_PERMANENTLY
HTTP_302_FOUND
Enter fullscreen mode Exit fullscreen mode
  • 400s 
HTTP_400_BAD_REQUEST
HTTP_401_UNAUTHORIZED
HTTP_403_FORBIDDEN
HTTP_404_NOT_FOUND
HTTP_405_METHOD_NOT_ALLOWED
HTTP_408_REQUEST_TIMEOUT
HTTP_415_UNSUPPORTED_MEDIA_TYPE
Enter fullscreen mode Exit fullscreen mode

Important to know the difference between 401 and 403 :

401 - No credentials, no token, unauthenticated

402 - No authorization for the resource, role not correct, not enough eprmissions. Basically e.g. you may want to access admin resources as a simple user.

Query parameters

Query resources via url parameters:

domain.com/cats?name=georgina&color=black
Enter fullscreen mode Exit fullscreen mode

Stick with conventional query parameters.

Versioning

If you are not working on a mobile app or in a bigger team you can skip it for now. This is very important if you are planning an API for a mobile app because app updates take long time to develop or deliver and it’s difficult to synchronise the changes with the backend. In case you are starting a project in a bigger team or a company, versioning is also extremly important since it allows more agile development - backenders don´t have to wait for front-enders. You can deploy your new API without worrying that you’ll break the client’s app. There is many REST API verioning strategies, at the end the goal is to maintain backward compatibility and avoid code duplication.

There is multiple possibilities of versioning schemes for your API:

  • Versioning via URL 
urlpatterns = [
    url(
        include('v1/registration',
        register_via_email
    ),
    url(
        include('v2/registration',
        register_via_oauth
    )
]
Enter fullscreen mode Exit fullscreen mode
  • Versioning via hostname: 
https://v1.yourdomain.com/registration/
https://v2.yourdomain.com/registration/
Enter fullscreen mode Exit fullscreen mode
  • Versioning via parameter: 
https://yourdomain.com/registration/?version=1
https://yourdomain.com/registration/?version=2
Enter fullscreen mode Exit fullscreen mode

Restful API best practices when it comes to way of versioning API - doesn’t exist. Remember that your case might be different and your needs differ too - choose what is the best solution for you depending on the circumstances. Google has a great source on versioning API, you should check it out before laying first lines of code.

Once you use versioning you can benefit from it like this:

def registration_type(self):
    if self.request.version == 'v1':
        return register_via_email(self.body.email, self.body.password)
    return register_via_oauth(self.body.token)
Enter fullscreen mode Exit fullscreen mode

SUM_UP: API Versioning is a great way to implement changes to code but it should be used if other methods are unavailable, use it conciously to not introduce unnecessary complexity.

Did you make any mistakes when using REST API or you’ve seen one here? Tell me about your insights. Leave a comment with YOUR opinion.

<!-- DOCS --><!-- EXAMPLES --><!--
photo_tag
-->

Top comments (0)

Read next

func25 profile image

Go Singleflight Melts in Your Code, Not in Your DB

Phuong Le -

garciadiazjaime profile image

React + AWS Cognito: Email Authentication Setup Guide (First Part)

Jaime -

lithephp profile image

Improving the Performance of Your PHP Application with Lithe Cache

Lithe -

daniel_haga_20e6b639d3605 profile image

GSAP Starter Template

Daniel Haga -