10 tips to create comfortable REST API

Valeriy — Fri, 23 Jul 2021 09:38:18 +0000

I'm backend engineer and biggest part of my career based on creating different APIs for services. Tips for this article were collected based on the most frequently faced issues on designing stage of team projects or using external APIs.

Chances are, you've come across terrible API providers. Working with them, as a rule, is associated with increased emotionality and misunderstanding. Some of these problems can be avoided by designing the application interface using the tips below.

1. Do not use verbs in url*

* - if you are going to implement one of CRUD-action

The CRUD request methods are responsible for the action with the resource: POST - create, GET - read, PUT / PATH - update , DELETE - delete (you know :)).

Badly:

POST /users/{userId}/delete - delete user
POST /bookings/{bookingId}/update - update booking

Good:

DELETE /users/{userId}
PUT /bookings/{bookingId}

2. Use verbs in url

You can use verbs in url to describe something diff than CRUD-action.

Badly:

POST /users/{userId}/books/{bookId}/create - link book with user

Good:

POST /users/{userId}/books/{bookId}/attach
POST /users/{userId}/notifications/send - send notify to user

3. Define new entities

Above there is an example of adding a book to a user, perhaps the logic of your application implies a list of favorites, then the route may be like this:

POST /favorite/{userId}/{bookId}

4. Try to use one resource identifier

This means if you have one-to-many records, for example: booking -> travellers, it will be enough for you to use only traveler identifier in the request.

Badly:

# getting travellers data
GET /bookings/{bookingId}/travellers/{travellerId}

Good:

GET /bookings/travellers/{travellerId}

Also note that /bookings/travellers is better than just /travellers. It's good to stick to the data hierarchy in your API.

5. All resources in plural

Badly:

GET /user/{userId} - getting users data
POST /ticket/{ticketId}/book - ticket booking process

Good:

GET /users/{userId}
POST /tickets/{ticketId}/book

6. Make the most of HTTP statuses

The easiest way to handle errors is to respond with an appropriate status code. In most cases, this status alone can provide comprehensive information about the result of request processing. Some of the most common response codes:

400 Bad Request - The client sent an invalid request, for example, a required request parameter is missing.
401 Unauthorized - The client was unable to pass mandatory server authentication to process the request.
403 Forbidden - The client is authenticated but does not have permission to access the requested resource.
404 Not Found - The requested resource does not exist.
409 Conflict - This response is sent when the request conflicts with the current state of the server. Example: trying to make an booking twice.
500 Internal Server Error - A general error has occurred on the server.
503 Service Unavailable - The requested service is not available. Example: slow work of backend code and, consequently, freezing of the general workflow of service.

7. Resource get modifiers

The routing logic may not be related to the project architecture or database structure. For example, the database contains quizzes and passed quizzes - two separate tables and entities (quizzes and passed_quizzes). But for api, it can be just quizzes, and passed quizzes are a modifier.

Route example: /quizzes and /quizzes/passed. Here quizzes - resource, passed - modifier.

Badly:

GET /passed-quizzes - getting passed quizzes
GET /booked-tickets - getting booked tickets
POST /gold-users - creating gold user

Good:

GET /tickets/booked
POST /users/gold

8. Choose one response structure

When on two different API requests can be received completely different response - it's sadly.

Try to form one clear structure that you will always adhere to. It will also be cool to include service fields that carry additional information.

Badly:

GET /book/{bookId}
{
    "name": "Harry Potter and the Philosopher's Stone",
    "genre": "fantasy",
    "status": 0, # статус вашего приложения
    "error": false, 
    ...
}

Good:

GET /book/{bookId}
{
    "status": 0,
    "message": "ok",
    "data": {...}
}

In this example, 3 fields are universal and can be used for any responses from your API. status - request-handling status of application. messages - text by which API-client can figure that happening. Both fields inform additional information about request processing, but they shouldn't include application data.

For example, in application at one time, a user can take only one quiz. Then a request to start new quiz can reply the 409 status code. In the status and message fields there will be additional information why the error has occurred.

9. All parameters and json in camelCase

9.1 Request params

Badly:

GET /users/{user-id}
GET /users/{user_id}
GET /users/{userid}

Good:

GET /users/{userId}
POST /ticket/{ticketId}/gold

9.2 In body of request or response

Badly:

{
    "ID": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
    "Name": "soccer3000",
    "provider_id": 1455,
    "Created_At": "25.05.2020"
}

Good:

{
    "id": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
    "name": "soccer3000",
    "providerId": 1455,
    "createdAt": "25.05.2020"
}

10. Use Content-Type

Don't make special routes for types, use Content-Type header instead.

Badly:

GET /tickets.json
GET /tickets.xml

Good:

GET /tickets
// in headers
Сontent-Type: application/json
// or
Сontent-Type: application/xml

The End

The tips listed above are not the whole list of ways to make the API better. For further study, I recommend that you discover the REST API specifications and the list of http status codes (you will be surprised how many of them and what situations they cover).

Let's share in comments your recommendations for building awesome APIs.

Happy coding!

Find All Numbers Disappeared in an Array - Go solutions

Valeriy — Fri, 23 Jul 2021 08:41:26 +0000

Hi everyone! Today, we will look at rather easy question from topic arrays. The most interesting in here - solution without using additional memory.

The question

Link: 448. Find All Numbers Disappeared in an Array.
Difficulty: easy

💡 Take 10-15 mins to find solution by yourself. If can't solve in-space time, let's keep reading.

Approach #1 - Extra space

func findDisappearedNumbers(nums []int) []int {
   hp := make(map[int]int)
   n := len(nums)
   res := make([]int, 0)

   for i := 0; i < n; i++ {
      hp[nums[i]]++
   }

   for i := 0; i < n; i++ {
      _, ok := hp[i+1]
      if ok == false {
         res = append(res, i+1)
      }
   }

   return res
}

Algorithm for input [4,3,2,7,8,2,3,1]:

We add all numbers to hash-map, it gives us like this:
```
{
    4: 1,
    3: 2,
    2: 2,
    7: 1,
    8: 1,
    1: 1
}
```
It's not necessary to count amount of each number in nums.
We know, highest value in array equals length of this array. Therefore we just need to find numbers from 1 to length which doesn't exists in create hash-map (don't exists in array) and save their to result array.
The biggest waste of memory happening because we use hash-map to store duplicate numbers. It clear that in worst case hash-map would use memory same as input array. So, it takes O(n) space complexity. Also, we have 2 passes through nums array, it takes O(2n) → O(n).

Approach #2 - in-space

func findDisappearedNumbers(nums []int) []int {
    for i := 0; i < len(nums); i++ {
        ind := abs(nums[i]) - 1
        if nums[ind] > 0 {
            nums[ind] = -nums[ind]
        }
    }

    j := 0

    for i := 0; i < len(nums); i++ {
        if nums[i] > 0 {
            nums[j] = i+1
            j++
        }
    }

    return nums[:j]
}

func abs(a int) int {
    if a < 0 {
        return -a
    }
    return a
}

Algorithm for input [4,3,2,7,8,2,3,1]:

We take every number and mark corresponding position as negative, like this:

i=0 -> nums[0] -> 4-1=3 -> nums[3] = -nums[3] -> [4,3,2,-7,8,2,3,1]
i=1 -> nums[1] -> 3-1=2 -> nums[2] = -nums[2] -> [4,3,-2,-7,8,2,3,1]
i=2 -> nums[2] -> 2-1=1 -> nums[1] = -nums[1] -> [4,-3,-2,-7,8,2,3,1]
...
i=6 -> nums[6] -> 3-1=2 -> nums[2] < 0 -> [4 -3 -2 -7 8 2 -3 -1]
i=7 -> nums[7] -> 1-1=0 -> nums[0] = -nums[0] -> [-4 -3 -2 -7 8 2 -3 -1]

[-4 -3 -2 -7 8 2 -3 -1]
[ 0  1  2  3 4 5  6  7]

As you can see above, there are two positive numbers, their indexes + 1 will be the disappeared digits we were looking for. We put their to the beginning of array and return calculated range of slice ( [5 6 -2 -7 8 2 -3 -1] and j=2).
It takes O(1) space complexity because we don't use any additional structures. We have two consecutive passes through array. It takes O(2n) → O(n) (discard constants) time complexity.

DEV Community: Valeriy

10 tips to create comfortable REST API

1. Do not use verbs in url*

2. Use verbs in url

3. Define new entities

4. Try to use one resource identifier

5. All resources in plural

6. Make the most of HTTP statuses

7. Resource get modifiers

8. Choose one response structure

9. All parameters and json in camelCase

9.1 Request params

9.2 In body of request or response

10. Use Content-Type

The End

Find All Numbers Disappeared in an Array - Go solutions

The question

Approach #1 - Extra space

Approach #2 - in-space