Как представить функции в API REST, которые на самом деле не являются ресурсами?

Question

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

Например: GET /user/profile/{id} или POST /user/profile.

Но не все функции могут быть представлены типичными ресурсами. Например, комбинация регистрационного ключа и секрета должна быть подтверждена. Как бы я представлял этот метод в REST API?

Answer 1

Конкретный ответ на ваш вопрос будет следующим:

POST to /RegistrationValidation
Request body:
{
    "key": "..."
    "secret": "..."
}

И вы ответите 200 OK, если полученные сервером данные верны, или каким-либо другим кодом состояния, если нет.

Суть в том, что:

• ваши ресурсы API не должны быть сопоставлены один к одному с вашей моделью домена.При разработке API не всегда следует придерживаться стиля CRUD.
• Вы можете свободно разрабатывать свой API в мелкозернистом , крупнозернистом стиле или смешивать их , если в конце концов он дружелюбен дляпотребитель-клиент.Любой глагол может быть «существительным», и вы получите новый ресурс.У вас может быть ресурс, который модифицирует несколько моделей базовых доменов для решения конкретной бизнес-задачи, и это вполне нормально.Но будьте последовательны в своих решениях и не забывайте, что свобода подразумевает ответственность.У вас бесконечное пространство URI, но убедитесь, что у вас не будет много ресурсов только потому, что вы можете.

Когда я писал этот ответ, я вспомнил, где я видел все эти рекомендации, и яя действительно рад, что эта статья 2014 года еще не вышла, я действительно рекомендую ее: https://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling

Answer 2

Как представить функции в REST API, которые на самом деле не являются ресурсами?

Практически все, о чем вы можете подумать, это ресурс.Из тезис Филдинга :

Ключевая абстракция информации в REST - это ресурс.Любая информация, которая может быть названа, может быть ресурсом: документ или изображение, временная служба (например, «сегодняшняя погода в Лос-Анджелесе»), коллекция других ресурсов, не виртуальный объект (например, человек) и т. Д.,Другими словами, любая концепция, которая может быть целью гипертекстовой ссылки автора, должна соответствовать определению ресурса.Ресурс - это концептуальное отображение на набор объектов, а не на объект, который соответствует отображению в любой конкретный момент времени.

target-uri - это просто идентификатор;это действительно может быть что угодно.Например,

/AAFE4035-C6E4-4897-B174-5FD0105DFF7A

- это прекрасный идентификатор ресурса.

Можно подумать об этом: идентификаторы ресурсов во многом похожи на имена переменных.Машины не заботятся о том, какое написание вы используете.Соглашения об орфографии существуют для людей.

Иногда эта эвристика помогает: как бы вы сделали это с веб-сайтом?Пользователь должен начать с некоторого URI с закладкой, а затем переходить по ссылкам и отправлять формы, пока работа не будет завершена.Какие идентификаторы вы бы использовали в этом случае?