Лучшие практики API могут быть любыми советами, которые ваша команда разработчиков хочет сообщить разработчикам о работе с API. Нет определенного количества тем, которые обычно рассматриваются в передовых методах API. Вместо этого, лучшие практики могут быть общим заголовком для контента, который нигде не подходит.
Какие темы включать в Best practices
Хотя многие из тем в документации API являются стандартными, обычно есть подробный список вещей, которые нужно знать о работе с API. Такую информацию можно получить только по запросу разработчиков.
Список тем может включать такие темы, как:
- разбиение на страницы,
- временные диапазоны,
- отказоустойчивость,
- значения кэша,
- возможности подключения,
- тайм-ауты,
- время простоя,
- SSL,
- версии,
- тестирование и проверка,
- экспорты,
- языки,
- обработка номеров,
- расширение ресурсов,
- уведомления,
- CORS.,
- локализация
и многое другое.
Примеры Best practices
Ниже приведены примеры Best practices по использованию API с нескольких сайтов документации по API.
Mailchimp
Best practices Mailchimp API включают советы по отказоустойчивости, использованию конкретных запросов, аутентификации, значениям кэша, подключению и регистрации. Благодаря отказоустойчивости Mailchimp напоминает разработчикам о том, что иногда случаются простои, поэтому они должны планировать соответствующую обработку сценариев, если API не отвечает. С помощью специальных запросов Mailchimp предупреждает пользователей о времени, которое может потребоваться, если запрос слишком общий, и, следовательно, возвращает слишком много информации.
Coinbase
Coinbase не ссылается на такие темы как лучшие практики; вместо этого навигационная панель показывает список тем. Пагинация - одна из этих тем, на которой стоит остановиться. Как нумерация страниц связана с API? Предположим, что конечная точка API возвращает все элементы в учетной записи пользователя. Может быть тысячи элементов, и если все элементы были возвращены в одном ответе, API может потребоваться много времени для сбора и возврата большого количества данных. В результате, как и при поиске в Google, ответ возвращает ограниченный набор, например первые десять элементов, а затем содержит URL-адрес, который можно использовать для перехода к следующему набору ответов. Разбиение на страницы относится к переходу на следующую страницу ответов.
Ранее, определяя характеристики REST, упоминалась HATEOS или «Гипермедиа как движок состояния приложения». Ссылки в ответах, которые возвращают больше результатов, являются одним из примеров HATEOS.
Программная обработка URL-адреса для получения большего количества ответов может быть довольно сложной задачей. Если нужно, чтобы все элементы были возвращены, а затем отфильтрованы и отсортированы, найдя конкретные значения для извлечения, как бы вы сделали это, используя URL-адрес, возвращенный в ответе? Команда может дать совет разработчикам, работающим с этими сценариями. Скорее всего, конечная точка будет предлагать фильтры в качестве параметров для применения к конечной точке, чтобы первоначальный ответ содержал требуемый набор элементов. Такой вид совета может быть уместен в лучших методиках API.
👨💻 Практическое занятие: Best practices
В своем найденном опен-сорс проекте найдем раздел Best practices. Ответим на вопросы:
- Существуют ли Best practices для работы с API, которые не вписываются ни в какие другие типичные темы API?
- Как организованы Best practices в существующей документации? Они перечислены в FAQ?
- Какие актуальные темы рассматриваются в Best practices?
- Есть ли в проекте проблемы, которые должны быть отражены в Best practices API?