Эта статья в основном предназначена для того, чтобы учиться у других, но я действительно хочу обобщить набор спецификаций для новичков, таких как я, чтобы использовать их для стандартизации кода. Если у вас есть какие-либо хорошие предложения, пожалуйста, дайте мне знать. Эта статья будет обновляться в течение длительного времени. время!
Во-первых, ключевые понятия:
REST, аббревиатура от Representational State Transfer. Мой перевод этой фразы - «переходы состояний на уровне представления».
Resource(ресурс): один экземпляр объекта. Например, животное. Это может быть текст, картинка, песня, служба, словом, конкретная реальность. Вы можете указать на него с помощью URI (унифицированного указателя ресурсов), и каждый ресурс соответствует определенному URI. Чтобы получить этот ресурс, просто посетите его URI, чтобы URI стал адресом или уникальным идентификатором для каждого ресурса.
собирать: Коллекция объектов. Например, животные.
третья сторона: разработчики, использующие наш интерфейс
Представление
«Ресурс» — это информационная сущность, которая может иметь множество внешних проявлений. Форма, в которой мы конкретно представляем «ресурс», называется его «слоем представления» (Representation).
Государственная передача
Посещение веб-сайта представляет собой интерактивный процесс между клиентом и сервером. В этом процессе обязательно будут задействованы данные и изменения состояния. Протокол Интернет-коммуникации HTTP-протокол — это протокол без сохранения состояния. Это означает, что все состояние сохраняется на стороне сервера. Следовательно, если клиент хочет управлять сервером, он должен использовать некоторые средства для осуществления «передачи состояния» на стороне сервера. И это преобразование основано на уровне представления, так что это «преобразование состояния уровня представления».
Средством, используемым клиентом, может быть только протокол HTTP. В частности, в протоколе HTTP есть четыре глагола, которые выражают режим работы: GET, POST, PUT, DELETE. Они соответствуют четырем основным операциям: GET используется для получения ресурсов, POST используется для создания новых ресурсов (а также может использоваться для обновления ресурсов), PUT используется для обновления ресурсов и DELETE используется для удаления ресурсов.
Например, текст может быть представлен в формате txt, формате HTML, формате XML, формате JSON или даже в двоичном формате; изображения могут быть представлены в формате JPG или PNG.
URI представляет только сущность ресурса, а не его форму. Строго говоря, имя суффикса «.html» в конце некоторых URL-адресов не нужно, потому что это имя суффикса указывает формат и относится к категории «уровень представления», а URI должен представлять только расположение «ресурса». Его конкретная форма должна быть указана в полях Accept и Content-Type в информации заголовка HTTP-запроса.Эти два поля являются описанием «уровня представления».
Мы суммируем, что такое спокойная архитектура:
(1) Каждый URI представляет ресурс;
(2) Между клиентом и сервером передается определенный уровень представления этого ресурса;
(3) Клиент управляет ресурсами на стороне сервера с помощью четырех глаголов HTTP для достижения «преобразования состояния уровня представления».
2. Спецификация интерфейса REST
1. Действие
ПОЛУЧИТЬ (ВЫБРАТЬ): получить определенный ресурс или список ресурсов с сервера. POST (CREATE): создает новый ресурс на сервере. PUT (UPDATE): обновить ресурс на сервере, предоставив весь ресурс. ИСПРАВЛЕНИЕ (ОБНОВЛЕНИЕ): Обновляет ресурс на сервере, предоставляя только измененные свойства. УДАЛИТЬ (DELETE): Удаляет ресурс с сервера.
Первый — это четыре с половиной действия: POST, DELETE, PUT/PATCH, GET. Поскольку PUT/PATCH можно считать только классом, это половина класса.
Есть также два менее известных HTTP-глагола: HEAD — получение метаданных о ресурсе, таких как хэш данных или время последнего обновления. OPTIONS — получает информацию о том, что клиенту разрешено делать с ресурсом.
2. Путь (название интерфейса)
Путь, также известный как «конечная точка», представляет собой конкретный URL-адрес API.
В архитектуре RESTful каждый URL-адрес представляет собой ресурс (resource), поэтому в 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Другой пример: если URI — /posts/show/1, где show — глагол, этот URI спроектирован неправильно. Правильным способом его написания должен быть /posts/1, а затем использовать метод GET для указания show.
Если какое-то действие не может быть выражено HTTP-глаголами, вы должны сделать это действие ресурсом. Например, онлайн-перевод, перевод 500 юаней со счета 1 на счет 2, неверный URI:
ПОЧТА /счета/1/перевод/500/на/2
Правильный способ его написания — заменить глагол «передача» на существительное «транзакция».Ресурс не может быть глаголом, но может быть услугой:
POST/транзакция HTTP/1.1
Хост: 127.0.0.1
от = 1 и до = 2 и сумма = 500,00
Уточните иерархическую структуру ресурсов. Например, если сфера деятельности — школы, то школы будут первичными ресурсами (/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 网关超时Использованная литература:
Руководство по разработке RESTful API — Руан Ифэн: http://www.ruanyifeng.com/blog/2014/05/restful_api.html