Вы правы, здесь много путаницы. Эксперты обычно ссылаются на «настоящие» REST API как на HATEOAS или API, управляемые гипермедиа, чтобы избежать этой путаницы. Большинство API, которые do называют себя REST API, обычно не являются.
Поэтому, когда вы разговариваете с другими инженерами о REST API, полезно сначала уточнить, что все считают REST, а не REST. Они не плохие инженеры, потому что не знают, что термин «ОТДЫХ» просто обрел собственную жизнь, и я бы сказал, что HATEOAS, вероятно, намного больше нишевого навыка.
Я согласен с ответом Николаса Шэнка о том, что во многих случаях универсальная вещь, которую нужно выяснить, если, например, DELETE работает, это фактически выпустить DELETE и посмотреть, сработает ли это впоследствии.
Это не всегда полезно, потому что многие люди, создающие API, захотят не показывать кнопку «удалить», если она все равно не будет работать.
Итак, что является разумным способом сообщить клиенту, что DELETE доступен? Стандарт HTTP на самом деле имеет заголовок Allow , который вы можете использовать, чтобы узнать, какие методы работают на данной конечной точке. Чтобы узнать, что это такое, вы можете отправить запрос OPTIONS. Не все фреймворки поддерживают это из коробки, но это законный способ сделать это.
Другой способ сообщить клиенту заранее - встроить эту информацию в ресурс, к которому вы обращаетесь. Пара примеров:
- ссылка на подсказку - это черновой стандарт Интернета, который может давать эти советы в самых разных местах, таких как HAL, заголовок HTTP Link или другие. Это в основном предлагает универсальный формат для этой информации.
- Если вы используете что-то вроде OpenAPI, вы можете добавить к своей спецификации API, какие методы будут и не будут работать. Это может хорошо работать в тех случаях, когда вы знаете, что
DELETE просто никогда не будет работать, но это не очень поможет вам в тех случаях, когда разные пользователи могут иметь разные уровни доступа, и некоторые люди могут использовать DELETE, а другие могут «т.
- Вы можете встраивать эту информацию в свой собственный формат, выражая ее как набор разрешений, возможно, в формате JSON, который ваше приложение понимает для интерпретации возможности выполнения определенных действий.
- Некоторые форматы HATEAOS явно содержат информацию о том, какие действия могут быть выполнены с помощью действий. Отличным примером является формат SIREN . HAL изначально не имеет этого.
В конечном счете, хороший формат HATEAOS не только вернет информацию о ресурсе и отношениях с другими, но также предоставит ряд возможных действий, которые можно предпринять. Большинство API REST, которые являются HATEAOS, обычно этого не делают, но HTML - лучший пример того, что делает. Если нет ссылки, кнопки или формы для выполнения действия, пользователь не может обнаружить это действие.
Пример ссылки-подсказки, встроенный в HAL
{
"_links": {
"self": {
"href": "/orders/523",
"hints": {
"allow": ["GET", "DELETE"],
}
}
}
}
Пример сирены
{
"class": [ "order" ],
"properties": {
"orderNumber": 523,
},
"actions": [
{
"name": "delete-order",
"title": "Delete Order",
"method": "DELETE",
"href": "/orders/523",
}
],
"links": [
{ "rel": [ "self" ], "href": "/orders/523" },
]
}
ВАРИАНТ ОТВЕТА
HTTP/1.1 200 OK
Allow: GET, DELETE