Переходя от теории версионирования API к практике, хочется подчеркнуть, что "достаточность" — это хороший критерий при разработке и модификации API:
- Да, можно на каждый чих переделывать половину проекта (AI-инструменты это прям провоцируют делать)
- Да, можно на каждое новое требование создавать новый endpoint и релизить без тестов на совместимость
- Да, можно для каждого клиента делать свой под-API и версионировать отдельно
- Да, можно требовать от каждого клиента, чтобы обновился "прям сейчас"
- Да, можно отбиваться от каждого желания фразами "вы можете это сделать, гланды через ... удаляются"
И да, делать всё выше перечисленное — это считать, что современный IT это про "правильно" или "честно", а не про то, как минимальными средствами получить максимум прибыли. Поэтому каждый раз нужно решать — какими минимальными действиями можно получить результат и как сделать так, чтобы этот результат не ударил по ноге в будущем.
Но всё это лирика, давай разберем, как на практике применять теорию. В материале рассмотрим конкретный код по версионированию API в Django REST Framework:
- Документирование API
- Выбор версии API: urlpatterns, HTTP-заголовки
- Реализация версии API: view, serializer
- Устаревание версии API: deprecated
- Тестирование версии API
Сейчас рассмотрим все шаги кроме тестирования, потому что тестирование новой версии API не отличается от простого тестирования — также нужно готовить данные, также проверять ответы.
1. Документирование API
API создается для взаимодействия с клиентом (иначе зачем создавать именно API), поэтому при создании новой версии хорошо задуматься, как его будут использовать. Посмотрим глазами клиента:
- Каким способом мне решить МОЮ задачу? (какие ресурсы, документация)
- Как получить доступ к этому способу? (авторизация)
- Как сделать запрос к этому способу (какой URL, какие данные нужны)
- Какой запрос решит мою задачу? (рабочие примеры в документации)
- Какие есть особенности решения? (ограничения, скорость и прочее)
Замечу, что клиенту в первую очередь хочется решить задачу, а не вдохновиться тем, какой прекрасный API был создан. Это уже после решения задачи можно сказать, что документация была прекрасная (в свое время Stripe удивил меня качеством проработки). При этом именно через документацию клиент ищет способ решения задачи.
Кстати, схожий паттерн "из конца в начало" применяется и в создании продуктов: Working Backwards от Amazon, Readme Driven Development.
А теперь переходим к DRF и как он помогает с документированием.