Как строить ответ вслух

Сначала проговори модель. Сущности здесь post, comment, author, like. Потом отношения: комментарии принадлежат посту, лайк - паре (пост, пользователь). И только потом рисуй таблицу ручек. Так видно, что ты проектируешь от домена, а не от «мне нужен endpoint».

GET    /v1/posts                    200                 список + пагинация
POST   /v1/posts                    201 + Location      создать
GET    /v1/posts/{id}               200 / 404 / 304     получить
PUT    /v1/posts/{id}               200 / 404 / 409     заменить целиком
PATCH  /v1/posts/{id}               200 / 404 / 422     частично изменить
DELETE /v1/posts/{id}               204 / 404           удалить
POST   /v1/posts/{id}/publish       200 / 409           смена состояния
GET    /v1/posts/{id}/comments      200 / 404           комментарии поста
POST   /v1/posts/{id}/comments      201 + Location      добавить комментарий
DELETE /v1/comments/{id}            204 / 403 / 404     удалить комментарий
PUT    /v1/posts/{id}/likes/me      204                 лайк (идемпотентно)
DELETE /v1/posts/{id}/likes/me      204                 снять лайк

Что обязательно проговорить

• PUT vs PATCH. PUT заменяет представление целиком и идемпотентен, отсутствующие поля трактуются как «сбросить». PATCH меняет ресурс частично; чтобы отличить «не прислал поле» от «прислал null», в Go нужен json.RawMessage или свой тип с UnmarshalJSON: указатель *string в обоих случаях останется nil. Иначе zero value затрёт данные.
• 201 с Location, а 204 - без тела вообще.
• 409 для оптимистичной блокировки: клиент шлёт If-Match: "v7", сервер сравнивает с текущим ETag. Не совпало, значит 412 Precondition Failed, а если версия пришла в теле, то 409 Conflict. Без этого два редактора молча затирают правки друг друга.
• Действия вне CRUD (publish, archive) оформляют под-ресурсом с POST, а не через PATCH {"status":"published"}, если публикация запускает побочные эффекты (рассылка, индексация): у неё своя авторизация и свои коды.
• Идентификаторы. Автоинкремент выдаёт объём базы и позволяет перебирать объекты (IDOR). Для публичного API берут UUIDv7 (сортируемый по времени) или ULID, а в JSON отдают строкой: JS теряет точность на числах больше 2^53.

В пути

GET /v1/posts/42

Плюсы: видно в логах, метриках и трейсах без разбора заголовков; тривиально маршрутизируется на уровне ingress (/v1/* → старый деплоймент, /v2/* → новый), и версии катятся независимо; кэши и CDN различают версии автоматически, потому что различается URL; можно прислать коллеге ссылку. Минусы: формально один и тот же ресурс получает два URI, и гипермедиа-ссылки (HATEOAS) начинают вести в конкретную версию; сохранённые клиентами ссылки привязаны к версии навсегда.

В заголовке

Accept: application/vnd.blog.v2+json
X-API-Version: 2
Stripe-Version: 2024-06-20

Плюсы: URI остаётся каноническим; это «правильный» HTTP через content negotiation; можно версионировать представление отдельно от ресурса; удобна модель Stripe, где версия привязана к аккаунту и меняется осознанно. Минусы: ничего не видно в access-логах и в браузере, отлаживать больно; обязателен Vary: Accept (или Vary: X-API-Version), иначе CDN отдаст клиенту v1 ответ версии v2; нужен дефолт для клиентов, забывших заголовок, и этот дефолт со временем становится ловушкой.

В query

GET /posts?version=2&tag=go

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

Два вида пагинации

Offset/limit: ?page=3&per_page=20 или ?limit=20&offset=40. Можно открыть любую страницу и узнать общее количество. Но за это платишь дважды: СУБД обязана прочитать и выбросить все пропускаемые строки (глубокие страницы стоят линейно дороже), а вставка или удаление сдвигает окно, и записи дублируются или пропадают между страницами.

Keyset (cursor / seek): WHERE (created_at, id) < (:ts, :id) ORDER BY created_at DESC, id DESC LIMIT 20. Курсор отдают непрозрачной base64-строкой с кортежем ключа последней отданной строки. По индексу СУБД сразу встаёт на нужное место, цена страницы постоянна, окно не «плывёт». Минус в том, что нельзя прыгнуть на произвольную страницу и дёшево посчитать total.

type Cursor struct {
    CreatedAt time.Time `json:"t"`
    ID        int64     `json:"i"`
}

func encodeCursor(c Cursor) string {
    b, _ := json.Marshal(c)
    return base64.RawURLEncoding.EncodeToString(b)
}

// составной ключ сравниваем именно кортежем, чтобы работал индекс:
// WHERE (created_at, id) < ($1, $2) ORDER BY created_at DESC, id DESC LIMIT $3

Лимит по умолчанию

• Дефолт 20 (для «тяжёлых» объектов 10, для лёгких справочников 50). Ориентир: ответ должен укладываться в сотни килобайт, а не мегабайты.
• Максимум 100. Больше отдают только через отдельную ручку экспорта с потоковой отдачей (NDJSON) или асинхронной выгрузкой в файл.
• Лимит больше максимума зажимают молча, а не отвечают 400: клиенту нужен результат, а не спор. А вот на limit=abc и limit=-5 ответ 400.
• Никогда не отдавать «всё», если параметра нет. Ручка без лимита похожа на мину: сегодня 300 строк, через год 3 миллиона.

Фильтрация и сортировка

• Плоские query-параметры: ?status=published&author_id=3&created_after=…. Язык запросов в URL не изобретают: сложные условия уходят в отдельную POST /v1/posts/search с телом (и да, это осознанное нарушение «POST не для чтения»).
• Несколько значений передают повтором параметра (?tag=go&tag=api), и r.URL.Query()["tag"] вернёт слайс.
• Сортировку пишут как ?sort=-created_at,title, минус = DESC. Поле маппится через map белого списка на выражение SQL. Плейсхолдеры в ORDER BY не работают, поэтому альтернативы белому списку нет.
• У каждого фильтруемого и сортируемого поля должен быть индекс, иначе API «работает», только пока таблица маленькая.

Определение и таблица методов

Операция идемпотентна, если N одинаковых вызовов оставляют систему в том же состоянии, что и один. GET/HEAD/OPTIONS safe и идемпотентны, PUT и DELETE идемпотентны, но не safe. POST ни то ни другое, PATCH - как напишешь. У DELETE второй вызов может вернуть 404, и идемпотентности это не отменяет: сравнивают состояние сервера, а не тело ответа.

Зачем это платежам

Клиент, получивший таймаут, не знает, дошёл ли запрос. Сеть теряет ответ, под перезапускается посреди обработки, балансировщик ретраит сам. Без защиты каждый такой случай оборачивается вторым списанием. При этом просто «не ретраить» нельзя: тогда часть платежей теряется.

Механика ключа - по шагам

1. Клиент генерирует UUIDv4 на бизнес-операцию (одна кнопка «оплатить» - один ключ) и переиспользует его во всех ретраях. Если генерировать ключ на каждый HTTP-запрос, толку от него нет.
2. Сервер пытается вставить строку (key, user_id, endpoint, sha256(body), in_progress). Уникальный индекс по key делает шаг атомарным: параллельную гонку выигрывает ровно один запрос.
3. Вставка удалась → выполняем операцию и идём в PSP со своим идемпотентным идентификатором (merchant_order_id), чтобы и там ретрай не задвоился.
4. Записываем status_code и тело ответа, переводим ключ в done, в идеале в той же транзакции, где меняется баланс.
5. Повторный запрос с тем же ключом: done → отдаём сохранённый ответ (полезно добавить Idempotent-Replay: true); in_progress → 409 Conflict с Retry-After; тот же ключ, но другой sha256(body) → 422: это ошибка клиента, а не ретрай.
6. Ключи живут ограниченное время (у Stripe 24 часа) и чистятся по expires_at. Уникальность обычно проверяют в паре (клиент, ключ), чтобы ключ одного мерчанта не блокировал другого.

-- занимаем ключ атомарно одним запросом
INSERT INTO idempotency_keys (key, user_id, endpoint, request_hash, state, expires_at)
VALUES ($1, $2, $3, $4, 'in_progress', now() + interval '24 hours')
ON CONFLICT (user_id, key) DO NOTHING
RETURNING key;
-- пусто в ответе => ключ уже занят, читаем существующую строку и смотрим state

RFC 7807 / 9457

Media type application/problem+json, поля: type (URI класса проблемы, де-факто он и служит стабильным кодом ошибки), title (короткое название, одинаковое для всех вхождений типа), status (дублирует HTTP-код, чтобы не потерялся при проксировании), detail (что именно пошло не так в этом вызове), instance (URI вхождения). В расширения кладут любые свои поля: trace_id, errors[] с разбивкой по полям, retry_after.

type Problem struct {
    Type     string       `json:"type"`
    Title    string       `json:"title"`
    Status   int          `json:"status"`
    Detail   string       `json:"detail,omitempty"`
    Instance string       `json:"instance,omitempty"`
    TraceID  string       `json:"trace_id,omitempty"`
    Errors   []FieldError `json:"errors,omitempty"`
}

func writeProblem(w http.ResponseWriter, p Problem) {
    w.Header().Set("Content-Type", "application/problem+json; charset=utf-8")
    w.Header().Set("X-Content-Type-Options", "nosniff")
    w.WriteHeader(p.Status)
    _ = json.NewEncoder(w).Encode(p)
}

// доменные ошибки маппятся в HTTP в одном месте, а не по хендлерам
func toProblem(ctx context.Context, err error) Problem {
    tid := trace.SpanContextFromContext(ctx).TraceID().String()
    switch {
    case errors.Is(err, domain.ErrNotFound):
        return Problem{Type: "/errors/not-found", Title: "Not found", Status: 404, TraceID: tid}
    case errors.Is(err, domain.ErrConflict):
        return Problem{Type: "/errors/conflict", Title: "Conflict", Status: 409, TraceID: tid}
    case errors.As(err, new(*domain.ValidationError)):
        // ... 422 + разбивка по полям
    }
    slog.ErrorContext(ctx, "unhandled", "err", err, "trace_id", tid) // детали только в лог
    return Problem{Type: "/errors/internal", Title: "Internal error", Status: 500, TraceID: tid}
}

Почему единый формат важнее его конкретного вида

Клиент должен уметь разобрать ошибку одной функцией и ветвиться по стабильному коду, а не по тексту сообщения. Как только в API появляются три разных формата ошибок (один в старых ручках, второй в новых, третий отдаёт nginx), клиентский код обрастает эвристиками вида «если в теле есть слово error». RFC 7807 удобен как готовое решение: его не надо обсуждать, а по Content-Type ошибку видно, даже не читая тело.

Почему нельзя светить внутренности

• Разведка перед атакой. Текст pq: relation "users" does not exist сообщает СУБД, схему и имя таблицы. Дальше подбирать инъекцию гораздо проще.
• Топология сети. dial tcp 10.0.3.17:6379: i/o timeout показывает внутренние адреса и состав инфраструктуры.
• Версии и пути. Стек-трейс выдаёт версию Go, структуру пакетов, путь сборки, а иногда и имя приватного репозитория.
• Оракул перечисления. «Пользователь не найден» vs «неверный пароль» превращает логин-форму в инструмент сбора валидных email. То же с 403 vs 404: разный код подтверждает существование объекта.
• Тайминг тоже утечка. Если «нет пользователя» отвечает за 5 мс, а «неверный пароль» за 80 мс (там честно считается bcrypt), разницу видно. Лечится так: хеш считают от заглушки, даже если пользователя нет.

Совместимые изменения

• Новое необязательное поле в ответе.
• Новый необязательный query-параметр или поле запроса с дефолтом.
• Новая ручка, новый метод у существующего пути.
• Ослабление валидации (было максимум 100 символов, стало 200).
• Новый заголовок ответа.

Ломающие изменения

1. Удаление или переименование поля ответа. Клиент получает zero value и не отличает его от «пусто».
2. Смена типа: "42" → 42, число → объект, скаляр → массив. encoding/json вернёт ошибку, статически типизированные клиенты упадут.
3. Новое обязательное поле запроса или новый обязательный заголовок.
4. Сужение допустимых значений: свободная строка стала enum, лимит уменьшился, формат даты стал строже.
5. Новое значение существующего enum в ответе ломает клиентов с полным перебором вариантов. Формально это добавление, а на деле авария. Поэтому в контракте изначально пишут: «неизвестные значения трактуйте как unknown».
6. Смена кода ответа или превращение синхронной ручки в асинхронную (200 → 202).
7. Изменение семантики при том же имени и типе: amount из рублей стал копейками, timeout из секунд стал миллисекундами, date сменил таймзону. Тихо испорченные данные хуже падения.
8. Изменение поведения: новый rate limit, ужесточённый maxLimit, другой порядок элементов, другая длина или формат идентификатора (клиент положил его в varchar(36), а ты выдал 40 символов).
9. Удаление ручки или изменение пути.

Закон Хайрама и его практический вывод

«При достаточном числе пользователей API неважно, что обещано в контракте: любое наблюдаемое поведение системы кем-то используется». Поэтому в реальности ломающими оказываются вещи, которых нет в документации: порядок элементов без ORDER BY, наличие поля debug, конкретная длина токена, время ответа. Отсюда вывод: явно писать в контракте, на что нельзя полагаться, и по возможности вносить небольшой контролируемый хаос (перемешивать порядок там, где он не гарантирован).