В последнее время я брал интервью у многих людей, и одна вещь, которую я видел снова и снова, даже от опытных разработчиков, заключалась в том, что они просто не понимают, как правильно проектировать REST API.

Если вы спросите 100 разработчиков программного обеспечения, знают ли они, что такое REST и как проектировать REST API, вы, вероятно, услышите, что почти 100 из них ответят утвердительно. Забавно, когда вы заставляете их разрабатывать пару простых конечных точек отдыха, они делают все, что не соответствует соглашениям REST.

Мое интервью довольно простое и прямолинейное, по крайней мере, я так думал, и цель вопроса — увидеть, на каком уровне вы понимаете REST API.

Мой вопрос на собеседовании состоит из двух частей:
1) Создайте конечную точку REST для получения определенного пользователя
2) Создайте конечную точку REST для обновления этого конкретного пользователя.

Вот некоторые из ответов, которые я вижу слишком часто, особенно от некоторых довольно старших разработчиков:

GET /users/getUser/1 для получения пользователя

POST /users/updateUser для обновления пользователя

Причина, по которой это неправильно, заключается в том, что по соглашению HTTP-глагол представляет действие, и мы должны использовать существительные для представления ресурсов, на которые действует глагол.

Правильная версия GET /users/getUser/1 просто GET /users/1. Использование глагола HTTP GET означает, что вы извлекаете некоторые данные. Это означает, что в URL-адресе нет абсолютно никакой необходимости в getUser. Вы можете думать об этом так: GET /users/1 = «получить пользователя, где id = 1».

Правильная версия POST /users/updateUser просто PUT or PATCH /users/1. Использование глагола HTTP PUT или PATCH означает, что вы обновляете некоторые данные. Это означает, что нигде в URL-адресе нет необходимости использовать updateUser. Вы можете думать об этом так: PUT or PATCH /users/1 = «обновить пользователя, где id = 1».

ПОЛОЖИТЬ против ПАТЧА

Многие думают, что запрос PUT является синонимом запроса PATCH, но на самом деле у них другое намерение. Обычно запрос PUT используется для замены всей записи, а запрос PATCH используется для обновления частичной записи.

В Интернете есть много мест, где можно прочитать об этом, включая здесь, здесь и здесь.

В REST нет жестких и быстрых правил, и есть множество обстоятельств, когда правила REST необходимо изменить в соответствии с вашими потребностями, но также есть так много общих случаев использования, которые не нужно выполнять 1,289432 миллиона раз. Простые операции REST должны следовать простым соглашениям REST. Период.