API это хорошо реализованный процесс работы с сервисом, котор может сильно ускорить интеграцию с с сервисом.
В сети сейчас представлен ряд готовых инструментов, которые умеют делать API и работать с ним. Однако, как показывает практика, они часто избыточны (реализация отнимает слишком много времени разработчика, тимлида, архитектора).
В настоящий момент, хорошим решением реализации API может быть GraphQL, но его недостаточно, потому что его идеология построена на:
А вот список того, что GraphQL не покрывает, но без этого никуда
Клиент - приложение, которое взаимодействует с Вашим API, и вот что ему нужно:
У клиента есть обязанности:
Эти обязанности значат, что клиент не должен впадать в ступор и должен отобразить пользователю адекватное сообщение, после чего может продолжать работу в штатном режиме.
Напомню, что сейчас довольно широко распространен подход REST и RESTful, о том, как его хорошо приготовить, я напоминаю ниже.
Чтобы реализовать данный подход, нужен отдельный фронт-контроллер, ниже я излагаю требования к нему.
1. Новый API фронт-контроллер должен:
2. Тип возвращаемых данных может отдаваться согласно указанному типу, в таком приоритете:
3. Версионность ни к чему не привязана, т.е. может инкрементироваться как-угодно под каждый роут, однако, версию надо указывать вначале роутинга, например:
4. Параметры в крупных компаниях именуют в snake_case. Думаю, нам стоит тоже так делать, даже не смотря на плюс кэмелкейса (удобно мапить передаваемые поля на поля моделей, реквеств-объектов), ведь:
5. Частичный ответ, должен уметь работать при любом типе запроса, например: /clients/007?fields=firstname,name,address
6. Поиск (фильтрация), должен уметь работать при любом типе запроса, например: /v1/restaurants/search?name=napoli*&type=chinese-or-japanese-and-italian и так далее:
'attribute:value AND | OR | NOT attribute:value'
'numeric_attribute = | != | > | >= | < | <= numeric_value'
'attribute:lower_value TO higher_value'
'facetName:facetValue'
'_tags:value,value2'
'attribute:value'
7. Сортировка, должна уметь работать при любом типе запроса, например: /v1/restaurants?sort=rating,reviews-desc,name-ask
В настоящий момент не продуманы моменты:
Еще, хотелось бы напомнить про некоторые нюансы.
Response не должен быть пустым, потому что в случае CORS запросов, браузеры по умолчанию могут получить доступ только к следующим заголовкам ответа:
Если требуется, чтобы клиентское приложение получило доступ к другим заголовкам, необходимо чтобы серер отдавал заголовок:
Access-Control-Expose-Headers: Access-Token, Uid
Таблица рекомендуемых возвращаемых значения основных методов HTTP в сочетании с URI ресурсов:
| HTTP Verb | CRUD | Entire Collection (e.g. /customers) | Specific Item (e.g. /customers/{id}) |
|---|---|---|---|
| POST | Create | 201 (Created), 'Location' header with link to /customers/{id} containing new ID. | 404 (Not Found), 409 (Conflict) if resource already exists.. |
| GET | Read | 200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists. | 200 (OK), single customer. 404 (Not Found), if ID not found or invalid. |
| PUT | Update/Replace | 405 (Method Not Allowed), unless you want to update/replace every resource in the entire collection. | 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid. |
| PATCH | Update/Modify | 405 (Method Not Allowed), unless you want to modify the collection itself. | 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid. |
| DELETE | Delete | 405 (Method Not Allowed), unless you want to delete the whole collection—not often desirable. | 200 (OK). 404 (Not Found), if ID not found or invalid. |
Представьте, что у вас на сайте публикуются статьи. У статей есть заголовок и содержание, которые вы можете редактировать.
PUT /articles/12
{
title: 'Новый заголовок',
content: 'Новое содержание'
}PATCH /articles/12
{
title: 'Новый заголовок',
content: 'Новое содержание'
}Итог: PUT и PATCH cработают идентично.
Вариант 2: вы изменяете только заголовок.
PUT /articles/12
{
title: 'Новый заголовок'
}PATCH /articles/12
{
title: 'Новый заголовок'
}Итог:
title и очистит поле content, потому что вы его не передали (PUT меняет объект целиком).title, не трогая поля content, потому что вы его не передали (PATCH изменяет отдельные поля ресурса).Удачки.
Источник: 1 - 2 Готовые решения: StrAPI (админка с автоматически создаваемым API с автоматически генерируемым сваггером)