Как написать удобный API — 15 рекомендаций07.08.2023 19:16

Разработка хорошего API требует особого внимания к деталям и соблюдения ключевых принципов программирования прикладных интерфейсов. Поэтому важно, чтобы у разработчиков были необходимые знания. Меня зовут Анастасия Иванова, я работаю в МТТ (входит в экосистему МТС) техническим писателем МТС Exolve. В этой статье я дам рекомендации по созданию API, которые помогут вам сделать его надёжным, масштабируемым и удобным в использовании. Самое интересное — под катом.

Общие рекомендации

Назначение.Перед разработкой чётко определите, для чего ваш API будет использоваться и какие возможности он должен предоставлять. Это поможет сосредоточиться на ключевых аспектах его настройки. При разработке интерфейса и функциональности проектируйте с учётом интересов пользователей, их потребностей и ожиданий.
Стандартизация и безопасность. Придерживайтесь определённых стандартов и соглашений по именованию ресурсов, методам запросов, формату данных и обработке ошибок. Используйте популярные протоколы и стандарты (REST или GraphQL), а также выберите удобный для вас формат данных (JSON или XML).

Защита данных. Реализуйте механизмы аутентификации, авторизации, чтобы предотвратить несанкционированный доступ к пользовательской информации. Например, мы используем Bearer Token для аутентификации при запросах к нашему API.
Производительность. Оптимизируйте ваш API для быстрого и эффективного выполнения запросов. Кешируйте часто запрашиваемые данные, чтобы избежать повторного выполнения одних и тех же запросов и снизить нагрузку на сервер.
Поддержка. Обеспечьте каналы связи с пользователями, где они могут задавать вопросы, сообщать об ошибках и получать дельные советы по использованию вашего продукта. Лучший способ поддержки — сообщество. Не знаете, что делать, — спросите на форуме.
Управление версиями, тестирование и отладка. Разработайте систему управления версиями вашего API, чтобы обеспечить обратную совместимость и беспрепятственное внесение изменений без нарушения работоспособности интерфейса для существующих клиентов. Пусть система работает как отдельный инструмент.
Постоянное обновление документации. После внесения изменений в продукт и тестирования стоит сразу же позаботиться об актуальности конкретных страниц с описанием API. Лучший способ добиться этого — сделать документацию фундаментальной частью разработки. Два хорошо известных инструмента — Swagger и Postman — как раз помогают в этом, они доступны для большинства сред разработки API.

Тестирование. Систематически тестируйте API при различных сценариях и обработке ошибок. Исправляйте обнаруженные проблемы и улучшайте его стабильность.
Масштабирование.Учтите эту возможность вашего API при росте числа пользователей и объёма запросов. Используйте горизонтальное и вертикальное масштабирование, кеширование и другие методы для обеспечения отзывчивости и надёжности.

Вот ещё больше рекомендаций по созданию API. Может быть, вам также пригодится Google JSON Style Guide.

Советы по созданию удобного API

Соглашения об именах

Существуют различия в номенклатуре и стилях. Точки доступа и входные/выходные параметры можно написать различными способами: camelcase, дефис, символ подчёркивания. При создании API стоит выбрать один стиль написания.

Единообразие в синтаксисе поможет избежать путаницы в коде и документации. А также пользователям будет легче читать документацию и использовать ваш API в разработке своих проектов.

Версии

Довольно часто API‑интерфейсы меняются после первого выпуска. Разработчики добавляют новые функции в сервис, появляются новые методы и точки доступа. Также разработчики делают улучшения в уже существующих методах, которые пользователи могли использовать в своих проектах. Если вы знаете, что ваш API‑интерфейс будет меняться, стоит изначально использовать версии. Один из часто используемых способов — использовать латинскую букву V (v + номер версии) в точке доступа.

Пример

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

Используйте коды состояния HTTP

Ценной функцией, доступной в HTTP, является статус. Он возвращается в ответе сервера в зависимости от результата действия, отправленного в запросе. Есть несколько типов статуса: 200 OK (успешный запрос) и ошибка (код 400, 401, 500 и другие). Если запрос успешный, вашему API стоит отдавать 200 OK статус. Если нет, то стоит отдавать статус ошибки и пояснения, чтобы пользователь понял, что было не так в его запросе. Например:

Создание голосовой SMS:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "cal55094238-bc5f-4b2d-8a95-5a20d7cbb5bc"
}

Неверный запрос:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "failed to parse token" // неправильно указан токен приложения
}

Все коды ответа HTTP вы можете найти в документации от Mozilla.

Используйте пагинацию и фильтрацию для удобства конечного пользователя

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

1. GET v1/product?limit=100
2. POST v1/GetList
{
    "limit": 40;
    "offset": 100
}

Используйте кеширование API, чтобы увеличить производительность

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

Использование кеша полезно при загрузке конфигураций и каталогов, которые многократно не меняются в течение долгого времени. При использовании кеша не забудьте включать информацию Cache‑Control в заголовки. Это поможет эффективнее использовать систему.

Пример кода на Python с использованием библиотеки Flask‑Caching и Redis в качестве внешнего кеша:

from flask import Flask 
from flask_caching import Cache
import requests

app = Flask(name)
cache = Cache(app, config={'CACHE_TYPE': 'redis', 'CACHE_REDIS_URL': 'redis://localhost:6379/0'})

@app.route('/api/data')
@cache.cached(timeout=60) # кеширование на 60 секунд
def get_data():
response = requests.get('https://api.example.com/data')
return response.json()

if name == '__main__':
app.run()

В этом примере при обращении к /api/data происходит проверка наличия результата в кеше. Если есть результат, он возвращается прямо из кеша. Если результата нет, выполняется запрос к https://api.example.com/data, результат сохраняется в кеше на 60 секунд и возвращается клиенту.

Напишите понятную документацию

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

Опираясь на документацию, разработчики будут интегрировать ваш API в свои проекты. API‑документация часто включает в себя несколько разделов. Например:

С чего начать — краткое описание, как начать работать с API (способ аутентификации, базовые методы)
API Reference — описание всех доступных методов
Инструкции — пошаговое описание, как реализовать определённую функциональность

Каждый раздел имеет свою ценность, но наиболее важным всё‑таки является API Reference. Именно Reference содержит информацию, которая необходима для взаимодействия с API:

способ аутентификации
точка подключения с указанием метода запроса (CRUD: GET, PUT, POST, DELETE)
поля входных и выходных данных
возможные ошибки
примеры запросов

Ссылки на руководства по созданию API

Введение в веб-API для новичков от Mozilla
Учебник. Создание веб-API с помощью ASP.NET Core от Microsoft
Проектирование веб-API RESTFUL от Microsoft

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