Как спроектировать API, которое не придется переписывать через полгода

[itt1b]

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

[savostin]

Ну а как же:

1. Проектирование публичного API, когда заранее неизвестны способы использования (ваши догадки всегда неверны)

2. Авторизация и аутентификация. Права, роли.

3. Если права пользователя не дают доступ к каким-то полям ответа - отдельный эндпоинт для каждой роли с соответствующей документацией и схемой или поля опциональные (валидация схемы коту под хвост) или nullable и как это все описать в доках?

4. REST, RESTful, RPC и различное понимание этих слов разными разработчиками.

5. Кеширование, мультизональность, заголовки, безопасность.

6. Что делать с GET если параметры не влезают в query string

7. На каком языке возвращать текст «поле email заполнено неверно»? И нужно ли заводить машиночитаемые коды ошибок для каждого поля?

8. И конечно же холивар: «товар» не найден - это 404 или 200 с ошибкой?

Удачного проектирования API ;)

[Elbrus128]

На каком языке

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

Если ничего не задано, то из файла err_msg_ru.txt или err_msg_en.txt, в зависимости от умолчаний проекта. А, так-то любой может записать файл err_msg_sw.txt, установить lang = sw, чтобы мой же код отвечал ему на суахили.

И нужно ли заводить машиночитаемые коды ошибок

Лучше завести. )) При стандартном подходе, когда есть отдельное описание на систему ошибок кода, это недолго.

[ivvi]

8. И конечно же холивар: «товар» не найден - это 404 или 200 с ошибкой?

Зачем холиварить? Если REST — 404. Если RPC-like — 200 с кодом и пояснением ошибки в теле.

[savostin]

404 - HTTP status code, означает, что запрошенный URL не найден. Никакого отношения к бизнес логике он не имеет.

[Elbrus128]

Первая иллюстрация в статье после списка ошибок 4xx поразила до глубины души!!!

Так держать! Нам — людям — не хватает качественных материалов в это жуткое время взрывного роста нейросетевого пустословия!

[ivvi]

Да, шедевральная иллюстрация. Без неё было как-то непонятно про коды ошибок, а с ней всё стало гораздо понятнее и нагляднее!!!11

[Elbrus128]

Угу. Я тоже читал-читал эти 4 пункта — нифига не понятно! А, как дальше мотнул, посмотрел картинку и как... понял всё! Очень наглядно!