Если вы создаете API (мы предполагаем, что здесь HTTP или REST API ) впервые, то есть несколько областей, которым может быть уделено меньше внимания, чем следует. В свою очередь, в дальнейшем это может стать источником проблем.
Сегодня мы рассмотрим некоторые из этих проблемных областей, чтобы помочь вам избежать ненужных проблем.
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).
