Skip to main content

Документироваие ошибок API при использовании Swagger или GraphQL

Объяснение в один абзац​

API-интерфейсы REST возвращают результаты с использованием кодов состояния HTTP, поэтому пользователь API должен знать не только о схеме API, но и о возможных ошибках - вызывающий может затем поймать ошибку и тактично ее обработать. Например, в документации по API может быть заранее указано, что HTTP-статус 409 возвращается, когда имя клиента уже существует (при условии, что API регистрирует новых пользователей), поэтому вызывающая сторона может соответственно отобразить лучший UX для данной ситуации. Swagger - это стандарт, определяющий схему документации API, предлагающую эко-систему инструментов, позволяющую легко создавать документацию в Интернете, см. экраны печати ниже.

Если вы уже приняли GraphQL для своих конечных точек API, ваша схема уже содержит строгие гарантии того, как должны выглядеть ошибки (описано в спецификации) и как они должны обрабатываться вашими инструментами на стороне клиента. Кроме того, вы также можете дополнить их документацией на основе комментариев.

Пример ошибки GraphQL​

В этом примере используется SWAPI, API-интерфейс Star Wars.

# should fail because id is not valid
{
  film(id: "1ZmlsbXM6MQ==") {
    title
  }
}
{
  "errors": [
    {
      "message": "No entry in local cache for https://swapi.co/api/films/.../",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "film"
      ]
    }
  ],
  "data": {
    "film": null
  }
}

Цитата блога: "Вы должны сообщить своим абонентам, какие ошибки могут произойти"​

Из блога Joyent, занял 1 место по ключевым словам "Node.js logging"

Мы говорили о том, как обрабатывать ошибки, но когда вы пишете новую функцию, как вы доставляете ошибки в код, вызвавший вашу функцию? … Если вы не знаете, какие ошибки могут произойти, или не знаете, что они означают, то ваша программа может быть исправлена ​​только случайно. Поэтому, если вы пишете новую функцию, вы должны сообщить своим абонентам, какие ошибки могут произойти и что они означают …

Полезный инструмент: Swagger Online Documentation Creator​

Swagger API Scheme