Эта статья написана Йенсом Грасселем, автором Образовательного курса Pure Functional HTTP APIs in Scala.

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

Сегодня мы сосредоточим внимание на некоторых из этих проблемных областей, чтобы помочь вам избежать ненужных проблем.

Вот основные проблемы, которые мы рассмотрим сегодня:

  • 1. Управление версиями
  • 2. Коды ошибок и сообщения
  • 3. Метод аутентификации
  • Заключительные мысли

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

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

Управление версиями, иногда называемое контролем версий, представляет собой процесс разработки программного обеспечения, предвосхищающий будущие обновления и сводящий к минимуму работу, необходимую для обновления системы. Лучшие формы управления версиями предполагают, что и ваша система, и внешние системы изменятся. Примерами могут быть такие вещи, как избегание жесткого кодирования, когда это возможно, или включение методов проверки версий внешних ресурсов перед их использованием.

Некоторые люди могут возразить, что их API «завершен» и изменений не будет. Однако это редко бывает правдой.

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

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

Существует два распространенных способа реализации управления версиями: управление версиями URI и заголовки HTTP.

Версии URI

Это наиболее часто используемая практика, и она довольно проста. Вы просто используете другой URI для своих версий API. Довольно часто вы видите такие вещи, как https://api.example.com/v1/ или даже https://api-v1.example.com/.

Очевидным недостатком этого является то, что пути доступа будут меняться с каждой версией. С положительной стороны: эта схема обычно очень проста в реализации и использовании.

HTTP-заголовки

Иногда считается наиболее важным, чтобы URI ресурса никогда не менялся. В этом случае версии API могут запрашиваться заголовками HTTP. Вы можете либо ввести собственные (например, Accept-API-Version: v1), либо злоупотреблять ошибкой, используя существующие, такие как Accept: application/vnd.example+json;version=1.0.

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

2. Коды ошибок и сообщения

Это должно быть ясно, но я не могу не подчеркнуть этого достаточно. Почему? Ну, я просто не в состоянии сосчитать количество API, которые я видел, которые с радостью вернут код состояния HTTP 200 и какое-то непонятное сообщение об ошибке в теле ответа.

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

Не забудьте включить в свой ответ полезную информацию/сообщения об ошибках. Такие вещи, как последний шаг, завершенный в процессе, время возникновения ошибки и имя неисправного компонента — все это хороший выбор. Это сэкономит вашим пользователям много времени при решении проблем и принесет вам положительную оценку. Однако есть крайние случаи, когда вы можете не захотеть включать подробные сообщения об ошибках из соображений конфиденциальности или безопасности. В общем, включите как можно больше информации, но не делитесь конфиденциальной информацией.

Еще одна лучшая практика — убедиться, что вы последовательны в своем формате сообщения об ошибке. Если ваше сообщение является текстом, можно вернуть только текст. С другой стороны, если вы хотите получить более конкретную информацию, например метрики, лучше иметь четкое различие между ними. Не торопитесь, чтобы разработать модель реакции на ошибку, которая может быть проанализирована клиентом, и вы сможете последовательно использовать ее в своей системе.

3. Метод аутентификации

Наконец, что не менее важно, давайте поговорим об аутентификации.

Аутентификация — это процесс проверки учетных данных пользователя перед тем, как он получит доступ к заданным функциям или набору данных. Он тесно связан с авторизацией, которая представляет собой процесс безопасной передачи соответствующих учетных данных новому пользователю. Короче говоря, системы аутентификации проверяют учетные данные, системы авторизации предоставляют соответствующие учетные данные.

Оба являются фундаментальной частью управления доступом, категории, состоящей из любых систем, обеспечивающих доступ к ресурсам на любом заданном уровне только авторизованным пользователям.

Конкретная реализация аутентификации зависит от вашего варианта использования, но лучше подумать об этом с самого начала. Простое «включение какого-либо уровня аутентификации» после релиза — верный путь к неприятностям.

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

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

Заключительные мысли

По мере того, как вы переходите к созданию своего следующего API, лучший совет — строить для будущего, а также для настоящего. Помня об этих советах, вы должны учитывать будущие болевые точки и смягчать их с самого начала.

Некоторые другие концепции, которые вы должны изучить:

  • Доставка вашего контента с использованием HTTP-согласования контента для возврата данных в формате, необходимом клиенту.
  • Кэширование! Да, посмотрите на свой вариант использования и рассмотрите возможность возврата правильных заголовков кэширования, чтобы клиенты не слишком часто опрашивали ваши конечные точки.
  • Если вы используете настоящий REST, взгляните на Hypermedia как механизм состояния приложения (HATEOA).

Чтобы помочь вам практиковать свои навыки работы с API, я создал обучающий курс Pure Functional HTTP APIs in Scala. Этот курс поможет вам объединить функциональное программирование и проектирование HTTP-сервисов для создания мощных серверных API. Вы получите практический опыт работы с различными чистыми и нечистыми реализациями, а также с готовыми для отрасли методами сравнительного анализа для проверки своей работы. К концу у вас будут все инструменты, необходимые для разработки API с использованием функционального Scala.

Удачного обучения!

Продолжить чтение об API на Educative

Начать обсуждение

Какие другие функции API обычно упускаются из виду? Была ли эта статья полезна? Дайте нам знать в комментариях ниже!