Api - готовим правильно

Казалось бы API это нечто простое, но хорошо реализованный процесс разработки API может сильно ускорить разработку ПО.

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

Решение

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

  • Доменная модель (модели и поля)
  • Доступ к скоупам/функциям-наборам/функциям-экшенам модели (сложные выборки, сортировки, группировки)
  • Работа с выше перечисленным на уровне написания SQL-подобного синтаксиса в виде графа

А вот список того, что GraphQL не покрывает, но без этого никуда 

  • Доступ к сервис-классам (классам, которые имплементируют себя в виде сервиса бизнес-логики или внешнего сервиса)
  • Администрирование доступа API-клиентов (разграничение доступа к выше перечисленному)
  • Администрирование API-клиентов (непосредственно клиенты, токены, лимиты запросов и т.п.)
  • Авто-документирование API (желательно OAS 3, желательно на основе описания анотаций в коде или YAML)
  • Расширение API-функционала поддерживающее совместимость прежних версий

Что нужно клиенту

Клиент - приложение, которое взаимодействет с Вашим API, что ему нужно:

  • Контракт - формальное описание договоренностей взаимодействия клиента и сервера (API). Контракт можно расширять, но нельзя изменять, таким образом требуется поддерживать обратную совместимость. Если необходимо нарушить контракт, то пишут новую версию API.
  • Транзакционность запросов

Напомню, что сейчас довольно широко распространен подход REST и RESTful, о том, как его хорошо приготовить, я напоминаю ниже.

REST

Чтобы реализовать данный подход, нужен отдельный фронт-контроллер, ниже я излагаю требования к нему.

1. Новый API фронт-контроллер должен:

  • как в крупных компаниях, следовать rest (get,post,put,patch,delete) - https://blog.octo.com/en/design-a-rest-api/
  • автоматически уметь работать с любой моделью (желательно без создания объектов)
  • иметь авто-роутинг моделей, в том числе с пагинацией двух видов:
    • клиент указывает только page_number и page_rows, /v1/restaurants?page=0-24
    • клиент указывает offset – limit, пример /v1/restaurants?range=0-24
  • должен иметь возможность расширять авто-роутинг, например адресация на любую функцию любого класса
  • роутинг будет имеет hyphen-ated именование, например: /api/v1.1/all-inclusive
  • урл не должен заканчиваться на слэш, вот плохо: /api/v1.1/all-inclusive/

2. Тип возвращаемых данных может отдаваться согласно указанному типу, в таком приоритете:

  • формат указан в заголовке, например 'Content-Type: application/json'
  • формат указан в расширении урл, например: https://stream.twitter.com/1.1/statuses/sample.json
  • по-умолчанию json

3. Версионность ни к чему не привязана, т.е. может инкрементироваться как-угодно под каждый роут, однако, версию надо указывать вначале роутинга, например:

  • было: /api/v1.1/sample.json
  • стало: /api/v2/sample.json

4. Параметры в крупных компаниях именуют в snake_case. Думаю, нам стоит тоже так делать, даже не смотря на плюс кэмелкейса (удобно мапить передаваемые поля на поля моделей, реквеств-объектов), ведь:

  • есть свагер и благодаря анотации может мапить как душе угодно (snake -> camel)
  • можем сделать функцию конвертации именования параметров, а для нового фронт-контроллера делать это по-умолчанию

5. Частичный ответ, должен уметь работать при любом типе запроса, например: /clients/007?fields=firstname,name,address

  • модели должны уметь поднимать данные частично
  • если запрос идет не к моделе, то хорошо бы реализовывать обработчики запросов, которые будут уметь "частичный ответ"

6. Поиск (фильтрация), должен уметь работать при любом типе запроса, например: /v1/restaurants/search?name=napoli*&type=chinese-or-japanese-and-italian

7. Сортировка, должна уметь работать при любом типе запроса, например: /v1/restaurants?sort=rating,reviews-desc,name-ask

В настоящий момент не продуманы моменты:

  • Авторизация клиента (что является публичным роутом, а что нет)
  • Доступ клиентов к полям моделей (например пароли, паспортные данные) будет реализован позже (возможно нужна будет админка или настройка доступа на уровне бд - но тут есть момент: внутренние системы с данными)
  • Вложенность данных (данные реляций)
  • В большинстве случаев HTTP-статус 422 приравнивают к 400 (т.е. 422 нет), стоит ли нам тоже так делать, или нет

Еще, хотелось бы напомнить про некоторые нюансы.

Response

Response не должен быть пустым, потому что в случае CORS запросов, браузеры по умолчанию могут получить доступ только к следующим заголовкам ответа:

  • Cache-Control
  • Content-Language
  • Content-Type
  • Expires
  • Last-Modified
  • Pragma

Если требуется, чтобы клиентское приложение получило доступ к другим заголовкам, необходимо чтобы серер отдавал заголовок:

Access-Control-Expose-Headers: Access-Token, Uid

Удачки.

Источник: 1

Оцени публикацию:
  • 0,0
Оценили человек: 0

Похожие статьи:

Справочники и учебники:


Предложения и пожелания:
Ваше имя:
Ваш E-mail:
Сколько будет Οдин + Τри
Главная
X

youtube.com/watch?v=7hFivbgIEqk

При полном или частичном использовании материалов данного сайта, ссылка на сайт "yapro.ru" обязательна как на источник информации.
Автоматический импорт материалов и информации с сайта запрещен.
Copyrights © 2007 - 2019 YaPro.Ru

Главная » Веб-мастеру » PHP »