API на основе REST, как правило, проще в использовании и начале работы со службами на основе SOAP, и обычно для создания сообщений и конвертов не требуются все виды генерации кода. Однако при создании API-интерфейсов или сервисов на основе REST часто упускают из виду или упускают из виду документацию. REST не имеет WSDL, который используется для описания службы (см. Раздел о WADL далее в статье), и часто говорят, что ресурсы REST должны быть самодокументируемыми. Даже если это легко сказать, обычно рекомендуется предоставить дополнительную документацию. В этой статье я покажу вам, что вы должны документировать и как вы можете предоставить эту документацию вместе со своим ресурсом.
Давайте сначала посмотрим на пример ресурса. Этот ресурс, показанный далее, представляет собой отчет, который вы можете сделать в своем местном муниципалитете. Например, вы замечаете, что светофор не работает или в дороге есть дыра. Ваш очень современный муниципалитет предлагает API на основе REST, который вы можете использовать для сообщения о таких событиях.
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
|
Content-Type: application/vnd.opengov.org.report+json;charset=UTF-8 {"report": { "self": "report-1", "status": "New", "location": "Corner of ninth street", "x-coordinate": 52.34, "y-coordinate": 4.34, "description": "There is ugly graffiti sprayed on the mailbox at the corner on ninth street", "date": "25-11-2010", "time": "15:46" "images": [ {"href": "images/image1.png"}, {"href": "images/image1.png"} ], "related":[ {"href": "../report-4"}, {"href": "../report-7"}, {"href": "../report-9"} ] "links": [ {"relation": "invalidation", {"relation": "duplication", {"relation": "relation", ] "comments": [] }} |
Службы REST часто называют самодокументирующимися. Если вы посмотрите на этот ресурс, вы можете быстро понять, что представляет собой этот ресурс. Содержит общую информацию о ресурсе:
|
01
02
03
04
05
06
07
08
09
10
|
"self": "report-1", "status": "New", "location": "Corner of ninth street", "x-coordinate": 52.34, "y-coordinate": 4.34, "description": "There is ugly graffiti sprayed on the mailbox at the corner on ninth street", "date": "25-11-2010", "time": "15:46" |
Показывает, где можно найти некоторые связанные ресурсы, например изображения, связанные с этим отчетом:
|
1
2
3
4
|
"images": [ {"href": "images/image1.png"}, {"href": "images/image1.png"} ] |
Или другие отчеты, связанные с этим отчетом:
|
1
2
3
4
5
|
"related":[ {"href": "../report-4"}, {"href": "../report-7"}, {"href": "../report-9"} ] |
Наконец, из этого ресурса вы также можете увидеть, как вы можете просматривать ссылки в этом ресурсе, чтобы сообщить о дублировании, аннулировать этот отчет или добавить связанный отчет:
|
1
2
3
4
5
6
7
8
|
"links": [ {"relation": "invalidation", {"relation": "duplication", {"relation": "relation", ] |
Как вы можете видеть, этот ресурс REST хорошо объясняет себя. Например, если мы хотим добавить комментарий к этому отчету, мы могли бы просто использовать PUT с сообщением с комментарием к / reports / report-1 / comments / URL. Но как выглядит это сообщение с комментариями? Как мы можем использовать ссылки? Для этого нам нужна дополнительная документация, чтобы прояснить наши намерения пользователям нашего сервиса.
Что вы должны описать, это следующие пункты:
- URL-адреса, используемые для доступа или поиска отчета;
- Связывает отношения, которые описывают, как различные ресурсы связаны друг с другом.
- Типы носителей, которые используются этим сервисом;
Давайте сделаем такое описание для этого сервиса. Первое, что мы опишем, это URL, по которому можно получить доступ к этой службе:
|
1
2
3
4
5
6
|
URLs:http://localhost:9002/opengov/reports?location=xPos,yPos&radius=rSubmit a GET request to this URL to search for Reports. You can optionally specify a location and a radius to only return reports for a specific area. If no location and radius are specified the first 100 reports, sorted by date (newest first), are returned. The reports that are returned have the application/vnd.opengov.org.report+json media type.xPos: x-coordinate of the location. Accepts GPS coordinates.yPos: y-coordinate of the location. Accepts GPS coordinates.r: radius to search for in meters. |
Эта часть документации описывает, как использовать наш поисковый сервис. Мы также явно определяем медиа-тип, который возвращает этот сервис. Таким образом, потребители уже знают, как действовать с результатами этой службы поиска.
Другим важным аспектом документации являются ссылки, которые мы определили:
|
1
2
3
4
5
6
7
8
|
Links:self: identifies the current resource. This (relative) URL can be used to directly access or modify a report. http://localhost:9002/opengov/invalidations/: This URL can be used to invalidate this resource. Use an HTTP PUT operation on this URL with media type application/vnd.opengov.org.invalidation+json. http://localhost:9002/opengov/duplications/: This URL can be used to mark a report as a duplicate. Use an HTTP PUT operation on this URL with media type application/vnd.opengov.org.duplication+json. http://localhost:9002/opengov/relations/: This URL can be used to relate two reports to each other. Use an HTTP PUT operation on this URL with media type application/vnd.opengov.org.invalidation+json. |
Здесь мы опишем, что означает конкретная ссылка, как ее использовать и какие типы медиа-данных ожидает эта ссылка. Это оставляет нас с описанием самих ресурсов. Если вы выполняете REST с XML, вы должны описать сообщение с помощью XSD. Если вы делаете JSON, вы можете использовать JSON-Schema, но я предпочитаю просто описывать поля для каждого типа медиа.
|
1
2
3
4
5
|
Media types:application/vnd.opengov.org.report+json- status: The status of this report- location: Readable description of the location of this report- etc. |
Если есть какие-либо ограничения на эти значения, это хорошее место для их описания. Помните, мы пишем эту документацию для потребления человеком, мы не требуем ее разбора. С пунктами, описанными выше, у вас есть очень хорошая отправная точка для создания документации для сервисов REST.
То, что вы должны иметь в виду, это следующие пункты:
- Следуйте основным принципам REST для операций HTTP PUT, GET, DELETE и POST.
- Используйте ссылки / ссылки при ссылках на другие ресурсы. На самом деле не имеет значения, используете ли вы относительные ссылки или абсолютные ссылки для этого, хотя относительные ссылки более гибкие, если вы перемещаете свой ресурс.
- Используйте типы носителей, чтобы проинформировать своего потребителя о типе ресурса, с которым он имеет дело.
- Используйте ссылки с определенным свойством отношения, чтобы сообщить своим потребителям, что вы можете делать с этим ресурсом.
- Добавьте простое описание URL-адресов, типов мультимедиа и ссылок, которые поддерживаются вашим сервисом.
Поскольку я ожидаю, что кто-то придет с этим вопросом, я отвечу на него заранее. Почему бы не использовать WADL для описания вашего REST API?
Пара причин:
- WADL больше фокусируется на коммуникации между машинами. Службы REST чаще создаются для взаимодействия с человеком. Не генерируя заглушку клиента
- WADL — хорошая концепция, но она склоняется к WSDL. WSDL часто используются для создания служб на основе RPC, которые скрывают базовый протокол. API-интерфейсы REST используются другим способом, где этот подход не очень хорошо подходит.
- Старая статья, но объясняет почему / почему не WADL довольно хорошо: http://bitworking.org/news/193/Do-we-need-WADL
Ссылка: Как должны документироваться службы REST? от нашего партнера JCG