RestFul API — это базовые знания, которые должен понять и освоить каждый программист.Когда мы проектируем API в процессе разработки, мы должны как минимум выполнять самые основные требования RestFul API (например, стараться использовать в интерфейсе существительные, использовать POST-запросы на создание ресурсов, DELETE-запросы на удаление ресурсов и т. д., например: GET /notes/id: Получить информацию о заметке с указанным id). Я столкнулся с этими вещами в процессе недавнего обучения, и у меня нет времени обобщать их, поэтому я поделюсь с вами несколькими хорошими статьями.
相关阅读：
• http://www.ruanyifeng.com/blog/2014/05/restful_api.html
(阮一峰，这篇文章大部分内容来源）
• https://www.baeldung.com/spring-hateoas-tutorial
(RestFul API Tutorial)
• https://aisensiy.github.io/2017/06/04/spring-boot-and-hateoas/
(Spring中使用HATEOAS)
• https://spring.io/guides/tutorials/bookmarks/
(Building REST services with Spring)
• https://www.baeldung.com/spring-hateoas-tutorial
(https://www.baeldung.com/spring-hateoas-tutorial)
Примечания: Возможно, вы раньше не имели большого контакта с HATEOAS. Я видел исходный код многих проектов, и они не соответствуют требованиям дизайна HATEOAS. Фактически, RestFul API лучше всего соответствует дизайну HATEOAS, то есть обеспечивает ссылки в возвращаемых результатах, ссылка на другие методы API позволяют пользователям узнать, что делать дальше, не проверяя документацию.
1. Важные понятия:
REST, аббревиатура Representational State Transfer, переводится как «преобразование репрезентативного состояния».
-
Ресурс: Один экземпляр объекта. Например, животное. Это может быть текст, картинка, песня, служба, словом, конкретная реальность. Вы можете указать на него с помощью URI (унифицированного указателя ресурсов), и каждый ресурс соответствует определенному URI. Чтобы получить этот ресурс, просто посетите его URI, чтобы URI стал адресом или уникальным идентификатором для каждого ресурса.
-
собирать: Коллекция объектов. Например, животные.
-
третья сторона: разработчики, использующие наш интерфейс
-
Представление: «Ресурс» - это некая информационная сущность, которая может иметь различные внешние проявления. Форма, в которой мы конкретно представляем «ресурс», называется его «слоем представления» (Representation).
-
Государственная передачаПосещение веб-сайта представляет собой интерактивный процесс между клиентом и сервером. В этом процессе обязательно будут задействованы данные и изменения состояния. Протокол Интернет-коммуникации HTTP-протокол — это протокол без сохранения состояния. Это означает, что все состояние сохраняется на стороне сервера. Следовательно, если клиент хочет управлять сервером, он должен использовать некоторые средства для осуществления «передачи состояния» на стороне сервера. И это преобразование основано на уровне представления, так что это «преобразование состояния уровня представления».
Основываясь на приведенном выше объяснении, давайте резюмируем, что такое архитектура RESTful:
(1) Каждый URI представляет ресурс;
(2) Какой-то уровень представления, который передает этот ресурс между клиентом и сервером;
(3) Клиент работает с ресурсами на стороне сервера с помощью команд HTTP (GET, POST и т. д.) для достижения «преобразования состояния уровня представления».
2. Спецификация интерфейса REST
1. Действие
GET （SELECT）：从服务器检索特定资源，或资源列表。
POST （CREATE）：在服务器上创建一个新的资源。
PUT （UPDATE）：更新服务器上的资源（客户端提供更新后的整个资源）。
PATCH （UPDATE）：更新服务器上的资源（客户端提供更改的属性，可以看做作是部分更新）。
DELETE （DELETE）：从服务器删除资源。
2. Путь (название интерфейса)
Путь , также известный как «конечная точка», представляет собой конкретный URL-адрес API.
В архитектуре RESTful каждый URL-адрес представляет собой ресурс, поэтому в URL-адресе не может быть глаголов, только существительные, а используемые существительные часто соответствуют именам таблиц базы данных. Как правило, таблицы в базе данных представляют собой «наборы» записей одного типа, поэтому существительные в API также должны стоять во множественном числе.
Например, если есть API, который предоставляет информацию о зоопарке (зоопарке), в него также входит информация о различных животных и сотрудниках, то его путь должен быть оформлен следующим образом.
Интерфейс максимально использует существительные и запрещает использование глаголов. Вот несколько примеров.
GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物
========反例：========
/getAllCars
/createNewCar
/deleteAllRedCars
Уточните иерархическую структуру ресурсов, например, сфера деятельности — школы, тогда школы будут первичными ресурсами (/school), учителя (/school/teachers), а ученики (/school/students) — вторичными ресурсами.
3. Управление версиями
следует указать номер версии API в URL-адресе. Такие как:https://api.example.com/v1/
Другой способ — поместить номер версии в HTTP-заголовок, но это не так удобно и интуитивно понятно, как указание его в URL-адресе. Github использует этот подход.
4. Фильтрация информации
Если количество записей велико, сервер не может вернуть их все пользователю. API должен предоставлять параметры для фильтрации возвращаемых результатов. Ниже приведены некоторые общие параметры.
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page_number=2&page_size=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。
比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。
5. Коды состояния
Диапазон кодов состояния
1xx 信息，请求收到，继续处理。范围保留用于底层HTTP的东西，你很可能永远也用不到。
2xx 成功，行为被成功地接受、理解和采纳
3xx 重定向，为了完成请求，必须进一步执行的动作
4xx 客户端错误，请求包含语法错误或者请求无法实现。范围保留用于响应客户端做出的错误，
例如。他们提供不良数据或要求不存在的东西。这些请求应该是幂等的，而不是更改服务器的状态。
5xx 范围的状态码是保留给服务器端错误用的。这些错误常常是从底层的函数抛出来的，
甚至开发人员也通常没法处理，发送这类状态码的目的以确保客户端获得某种响应。
当收到5xx响应时，客户端不可能知道服务器的状态，所以这类状态码是要尽可能的避免。
Код состояния и подсказка, возвращаемые сервером пользователю, следующие (в квадратных скобках указан HTTP-глагол, соответствующий коду состояния).
200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：
用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
502 网关错误
503 Service Unavailable
504 网关超时
3. ХАТЕОАС
Вышеизложенное является самой базовой вещью RESTful API, и это также проще всего практиковать в нашем обычном процессе разработки. На самом деле RESTful API лучше всего делать Hypermedia, то есть предоставлять ссылки в возвращаемых результатах для подключения к другим методам API, чтобы пользователи могли знать, что делать дальше, не проверяя документы.
Например, когда пользователь делает запрос в корневой каталог api.example.com, он получит такой документ.
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}
Приведенный выше код показывает, что в документе есть атрибут ссылки, и пользователь может прочитать этот атрибут, чтобы узнать, какой API вызывать дальше. rel представляет связь между этим API и текущим URL-адресом (связь коллекции и дает URL-адрес коллекции), href представляет собой путь API, title представляет заголовок API, а type представляет тип возвращаемого значения. API гипермедиа называется HATEOAS.
В Spring есть библиотека API под названием HATEOAS, с помощью которой мы можем более легко создавать API, соответствующие дизайну HATEOAS.
作者：xxx
链接：https://mp.weixin.qq.com/s/NY9zmuZdTAxjXRPb81i1fQ
来源：微信公众号-java程序媛之家