18. "Методические рекомендации по публикации открытых данных государственными органами и органами местного самоуправления, а также технические требования к публикации открытых данных. Версия 3.0" (утв. протоколом заседания Правительственной комиссии по координации деятельности Открытого Правительства от 29.05.2014 N 4)

Случаи использования API

API для доступа к открытым данным следует использовать для предоставления доступа к информации, имеющей одно или несколько свойств из следующего списка:

- большие объемы информации;

- часто меняющаяся информация;

- осуществление специфической выборки данных набора.

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

Методы API

В текущей версии Методических рекомендаций рекомендуется реализовывать только методы для просмотра и чтения данных. Добавление, обновление/изменение и удаление данных данной версией Методических рекомендаций не предусмотрено, все вызовы API реализуются HTTP-методом GET.

Адрес доступа к API

Располагайте API интерфейс на отдельном домене - api.example.com, opendataapi.example.com; или в отдельном разделе - example.com/api, example.com/opendataapi.

Адреса вызовов API

Рекомендуется использовать понятные адреса для доступа к информации:

- /showrooms - все выставочные залы Москвы;

- /showrooms/2345 - информация о конкретном выставочном зале.

В базовых адресах рекомендуется использовать существительные во множественном числе без использования глаголов. Конкретные имена лучше абстрактных, так, например: showrooms лучше, чем items.

Рекомендуется базовые адреса делать короткими и простыми, без множества параметров. Все дополнительные параметры рекомендуется указывать в параметрах запроса после знака "?".

Формат ответа API

Так как целевыми потребителями API будут в основном разработчики мобильных приложений и приложений для официальных сайтов, рекомендуемым форматом ответа является JSON. Альтернативным форматом ответа может быть XML.

Если ваш API реализует несколько форматов ответа, то необходимо предусмотреть указание формата в вызове. Лучше всего указывать его в адресе вызова:

/showrooms.json/2345

/showrooms.xml/2345

Также можно передавать формат ответа параметром в запросе:

/showrooms/2345?type=json

/showrooms/2345?type=xml

В случае если формат ответа не был задан в явном виде, API должен поддерживать ответ в формате по умолчанию.

Версионность API

Обязательно предусмотрите возможность выставления версии API при выполнении запроса.

Как реализовывать версионность API?

Номер версии рекомендуется указывать целым числом, без точек; перед номером версии рекомендуется добавлять символ "v".

Рекомендуемым подходом является явное указание версии API в адресе API запроса - api.example.com/v1/showrooms/2345

Также можно передавать номер версии параметром в запросе - api.example.com/showrooms/2345?version=v1

Постраничный ответ

API должен предусматривать постраничный ответ. По умолчанию достаточно отдавать 10 элементов с нулевым смещением.

Постраничность рекомендуется реализовывать в виде двух параметров запроса - число элементов (limit) и смещение (offset):

/showrooms?offset=50&limit=10

В ответе рекомендуется сообщать обратно клиенту параметры запроса и общее число элементов, доступных для запроса.

    {
      "status": "200",
      "request": {"limit": "10", "offset": "50"},
      "meta":{"total": "2035"},
      "results": {...}
    }

Частичный ответ

Частичный ответ подразумевает отправку в ответе только запрошенных атрибутов элементов данных. Нужные атрибуты перечисляются через запятую в параметрах запроса.

/showrooms?fields=name,address

Наименование атрибутов

Атрибуты рекомендуется именовать следуя конвенции camelCase. Но можно выбрать и другую конвенцию, главное следовать ей для наименования всех атрибутов.

Поиск

Ваш API может предлагать интерфейс поиска по данным.

/search?q=search+phrase

/search.xml?q=search+phrase

/showrooms?q=search+phrase

Примеры API запросов и ответов

Запрос:

GET http://api.example.com/v1/showrooms?type=json&limit=3

Ответ:

    {
      "status": "200",
      "request": {"api": "v1", "type": "json", "limit": "3"},
      "meta": {"total": "2034"},
      "results": {
        {"name":   "ГБУК  г. Москвы   "Выставочный   зал   "Солянка   ВПА",
"district":   "Центральный   административный   округ",  "area": "Басманный
район",  "address":  "улица  Солянка,  дом 1/2,  строение 2",  "telephone":
"(495) 621-55-72; (495) 621-59-61"},
        {"name": "ГБУК г. Москвы "Выставочный зал "Творчество", "district":
"Центральный административный округ", "area": "Таганский район", "address":
"Таганская улица, дом 31/22", "telephone": "(495) 678-55-78"},
        {"name": "ГБУК г. Москвы "Московский выставочный зал  "Галерея A3",
"district":  "Центральный  административный  округ", "area": "район Арбат",
"address":    "Староконюшенный    переулок,    дом    39",     "telephone":
"(495) 697-14-56"}
      }
    }

Запрос:

GET http://api.example.com/v2/showrooms/3

Ответ:

    {
      "status": "200",
      "request": {"api": "v2", "id": "3"},
      "meta": {},
      "results": {
        {"name": "ГБУК г. Москвы "Московский выставочный зал  "Галерея A3",
"district": "Центральный  административный  округ",  "area": "район Арбат",
"address":    "Староконюшенный    переулок,    дом    39",     "telephone":
"(495) 697-14-56"}
      }
    }

Запрос:

GET

http://api.example.com/v1/showrooms?limit=2&offset=1&fields=name,area,address

Ответ:

    {
      "status": "200",
      "request":  {"api":  "v1",  "limit":  "2",  "offset":  "1", "fields":
"name,area,address"},
      "meta": {"total": "2034"},
      "results": {
        {"name": "ГБУК г. Москвы  "Выставочный  зал  "Творчество",  "area":
"Таганский район", "address": "Таганская улица, дом 31/22"},
        {"name":  "ГБУК г. Москвы "Московский выставочный зал "Галерея A3",
"area": "район Арбат", "address": "Староконюшенный переулок, дом 39"}
      }
    }