По мере роста спроса на микросервисы разработчики начинают разбивать свой код на небольшие части и делать их «микро». Чтобы соединить все эти небольшие фрагменты, хороший дизайн API может сэкономить вам много времени.

Вы используете правильный протокол HTTP? Рой Филдинг (соучредитель протокола HTTP) указал, что большинство людей злоупотребляют им. Например, удалить запись: delete/{id} или обновить запись: update/{id}, это плохой дизайн для API.

Для современных веб-служб Рой Филдинг предложил REST API (интерфейс прикладного программирования для передачи репрезентативного состояния). Идея REST заключается в разделении действий и ресурсов с помощью GET, DELETE, POST и PUT для управления ресурсами.

Плохо спроектированный REST API = пустая трата времени!

Ресурс - это объект, который относится к данным и имеет методы для управления ими. Например, «школа, класс, учащиеся» - это ресурсы, а «удалить, добавить, обновить» - методы для управления ими.

Коллекции - это группа ресурсов. Например, «Лига плюща» включает Гарвард, Йель, Принстон и Колумбию.

URL - это путь для получения определенных ресурсов и применения к ним некоторых методов.

Используйте только существительное (не глагол!) В API

❌ Помещайте действия (глаголы) в пути URL

Посмотрите на примеры API ниже: -

/getAllStudents (To view all students)
/addNewStudent (To add 1 student)
/updateStudent (To edit 1 student)
/deleteStudent (To delete 1 student)
/deleteStudents (To delete many students)
/getStudentsFromCategory1 (To filter students from category 1)

Вы можете заметить, что список конечных точек API будет бесконечно расширяться, чтобы обслуживать все больше и больше операций. Это очень беспорядочно, особенно когда дело касается технического обслуживания.

✔️ Сохранять только имена (существительные)

Хороший пример - /students. Но как сказать серверу, что делать с этими записями? Просто показать или удалить их все? Вот почему нам нужны HTTP-методы (GET, POST, PUT, DELETE). Кроме того, конечная точка ресурсов всегда должна быть множественного числа, иначе мы должны передать name или id, чтобы указать один (например, /student/marry-christine или /student/123-888-999). Кроме того, все имена конечных точек должны быть: -

  1. Строчные символы (/student вместо /Student)
  2. Использование разделителя «-» (/school-name вместо /schoolName)
GET /students (To view all students)
POST /student (To add 1 student)
PATCH /student/{id} (To edit 1 student)
DELETE /student/{id} (To delete 1 student)
DELETE /students (To delete many students)
GET /students?filter={"category" = 1} (To filter students from category 1)

Вложенные ресурсы в API

Некоторые ресурсы взаимосвязаны друг с другом (родитель-потомок). Например, есть 2 школы (Гарвард, Принстон), в которых обучается соответственно 30 000 и 20 000 учеников. Итак, чтобы разработать API, он должен выглядеть примерно так: -

GET /schools/harvard/students (To view all students from Harvard)
GET /schools/harvard/student/kingsley (To get a student with name of Kingsley from Harvard)
DELETE /schools/princeton/student/mike (To delete a student with name of Mike from Princeton)

Формат JSON

Формат JSON имеет более высокую читаемость и масштабируемость по сравнению с другими форматами, например. XML, YAML. Он подходит для различных сред, легче декодируется для языков. Следовательно, в настоящее время он широко используется крупной технологической компанией при предоставлении API третьим лицам.

❌ Тело JSON с повторяющимися тегами:

{
 “studentName”: “Kingsley Tan”,
 “studentID”: “123–888–999”
}

✔️ Извлеките повторяющуюся часть как объект:

{
 “student”: { 
   “name”: “Kingsley Tan”,
   “ID”: “123–888–999”
 }
}

HTTP-методы

Конечные точки API похожи на предложения, где ресурсы - это существительное, а методы HTTP - действия.

ПОЛУЧИТЬ: для просмотра и чтения данных ресурсов, никаких других последствий. (Например, GET/schools/harvard/students вернет всех студентов Гарварда)

POST: чтобы запросить сервер для создания данных ресурсов в базе данных, в основном используется при отправке форм. (Например, POST /schools/harvard/student/kingsley предназначен для создания студента с именем Kingsley в базе данных Гарвардского университета.) Примечание. При выполнении нескольких действий POST будет создано несколько записей.

PUT: для обновления или создания (для новой записи) данных ресурса. (Например. PUT /schools/harvard/student/kingsley предназначен для обновления или создания студента с именем Kingsley в базе данных Гарвардского университета.) Примечание. Несколько действий PUT создадут только одну запись.

УДАЛИТЬ: для удаления данных ресурса из базы данных. (Например, УДАЛИТЬ /schools/harvard/student/kingsley означает удалить студента с именем Кингсли из базы данных Гарвардского университета.)

Статус HTTP

Когда клиентская сторона запрашивает с сервера через вызовы API, клиентская сторона должна получить обратную связь, успешно или нет. Статус HTTP - это серия стандартизованного кода, определяющего возможные ситуации, возникающие при HTTP-вызовах.

В большинстве случаев мы будем видеть ошибки, встроенные в тело ответа, т. Е. типичные code и message. Если для этого нет причины, иначе постарайтесь избегать этой структуры. Лучше всего было бы использовать код HTTP для классификации ошибок и объяснения подробных причин в сообщении об ошибке (теле).

Здесь мы приводим несколько общих примеров статусов HTTP: -

1xx - информационный

100: Продолжить. Предварительный ответ, информирующий клиентскую сторону о продолжении запроса или игнорировании, если он уже завершен.

2xx - Успешно

200: Хорошо. Стандартный код успешного ответа для GET, PUT или других методов.

201: ответ сервера после успешного создания. Например, POST /student/kingsley вернет код состояния 201 после создания.

204: Нет содержимого. Успешно выполнено, но содержимое не возвращается.

3xx - перенаправление

304: Не изменено. На стороне клиента уже сохранены соответствующие ответы в кеше, вместо этого используйте сохраненное значение.

4xx - ошибка на стороне клиента

ошибка 400, неверный запрос. Сервер не может разрешить запрос со стороны клиента.

401: Несанкционированный. На стороне клиента запрещен доступ к ресурсам, повторите попытку с правильным токеном доступа.

403: Запрещено. На стороне клиента прошел процесс проверки личности, однако ему не разрешен доступ к определенной странице или ресурсам (например, ограничение уровня доступа). Например, роль редактора не может добавлять / удалять пользователей в учетной записи.

404 Не Найдено. Запрошенная страница или ресурс больше не доступны.

410: Ушла. Запрошенная страница или ресурс удаляются и больше не доступны.

5xx - ошибка на стороне службы

внутренняя ошибка сервера 500. Правильный запрос получен, однако произошла неизвестная ошибка сервера (например, сервер не работает, проблема с пропускной способностью).

503 Сервис недоступен. Сервер выключен и не может принимать или обрабатывать какие-либо запросы. В большинстве случаев это происходит во время периода обслуживания сервера.

Поиск, фильтр и разбивка на страницы

Все эти API вызывают одну и ту же конечную точку, для этой операции не будет нового API.

GET /schools?search=harvard Искать Гарвардский университет из всех школ.

GET /schools?sort=rank_asc Ранжировать школы по возрастанию.

GET /schools?location=US Чтобы получить все школы в США.

GET /schools?page=6 Для перехода на страницу № 6 разбитого на страницы списка школ.

Управление версиями

API можно управлять в различных версиях, чтобы разделить различные функции или этапы разработки. Например:-

https://api.resources.com/v1/schools
https://api.resources.com/v2/schools

Обратите внимание, что пути содержат информацию о версиях (/v1 или /v2). V1 может быть производственной версией, а V2 - бета-версией. Таким образом, разработчики могут переключить всех пользователей на V1 на этапе разработки и перейти на V2, просто изменив путь после завершения.

Вывод:

  1. Все конечные точки API должны быть написаны строчными буквами.
  2. Используйте «-» в качестве разделителя текста (например, название школы).
  3. Используйте формат JSON.
  4. Контроль версий API (например, v1, v2).
  5. Использовать метод HTTP по умолчанию для всех операций.
  6. Используйте правильный статус HTTP для значимого кода статуса в ответе.

Отличный дизайн API - это как балерина, выступающая перед вами на сцене, насколько это элегантно. Надеюсь, это поможет вам лучше разрабатывать API!