У Мартина Фаулера есть хорошее резюме модели зрелости Ричардсона и то, что нужно для предоставления услуги RESTful.Ян сослался на один из постов Роя Филдинга, но есть некоторые шаги, которые нужно позаботиться в дополнение к гипермедиа (и HATEOAS ).
Применительно к модели Ричардсона Я думаю, что вашему API понадобятся некоторые изменения, чтобы добраться до "Уровня 3" (duh duh duhhhh).Коллекция /v1/inbox/messages выглядит звучащей, и только поддержка GET указывает, что это ресурс только для чтения для пользователя.Однако POST действие и идентификаторы для /v1/inbox/mark и /v1/inbox/archive только туннелируют службы в стиле RPC через HTTP - «Уровень 0» в статье .
Я бы предложил что-то вроде следующего как наивный, не гипермедиа (то есть "Уровень 2") API:
Чтобы получить список сводной информациивсех сообщений (во всех папках):
GET /v1/messages HTTP/1.1
Host: api.mydomain.com
Ответ:
content-type: text/xml
<?xml version="1.0"?>
<messages>
<message subject="Subject" unread="true" id="1234" folder="inbox" />
<message subject="Hello, world" unread="false" id="24" folder="inbox" />
...
</messages>
Чтобы получить полное сообщение:
GET /v1/messages/1234 HTTP/1.1
Host: api.mydomain.com
Ответ:
content-type: text/xml
<?xml version="1.0"?>
<message subject="Subject" unread="true" id="1234" folder="inbox">
Hi, this is the message.
</message>
Чтобы отредактировать сообщение (например, пометить его как прочитанное и переместить в папку архива):
POST /v1/inbox/messages/1234 HTTP/1.1
Host: api.mydomain.com
content-type: text/xml
<?xml version="1.0"?>
<message id="1234" unread="false" folder="archive" />
Примечание:здесь я намеренно использую POST вместо PUT для указания частичного обновления.
Другие вещи, которые требуют повышенного внимания:
Гипермедиа-ответы и типы мультимедиа.Честно говоря, это лучше объяснить другим (например, книга REST In Practice или пример InfoQ Coffee Cup тех же авторов), но вкратце ваши ответы должны указывать клиенту, чтодругие действия могут быть возможны из ответа на их самый последний запрос и позволяют им обнаруживать весь API из одного URI.В качестве примера приведено описание папок коллекций выше.Если GET /v1/messages/1234 вернуло:
<message subject="Subject" unread="true" id="1234" folder="inbox" >
Message text here.
<link rel="folder" href="http://api.mydomain.com/v1/folders/inbox" />
</message>
, тогда у клиента будет конкретный пример URI, чтобы попробовать OPTIONS, и хорошее представление о том, что там может быть.
Коды ответов и содержание: 200 OK очевидно.Ответьте 403 Forbidden, если пользователь не авторизован для просмотра определенного сообщения, 404 Not Found, если идентификатор сообщения не существует.Каждый раз, когда вы возвращаете ошибку, сообщайте клиенту, как исправить его запрос (если это возможно).