18. Приложение 10. Методические рекомендации по инструменту доступа к открытым данным (API)

18. Приложение 10. Методические рекомендации по инструменту доступа к открытым данным (API)

Случаи использования 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/2 34 5?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": "2 035"},

"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) 62159-61"},

{"name": "ГБУК г. Москвы "Выставочный зал "Творчество"", "district": "Центральный административный округ", "area": "Таганский район", "address": "Таганская улица, дом 31/22", "telephone": "(495) 678-55-78"},

{"name": "ГБУК г. Москвы "Московский выставочный зал "Галерея А3"", "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": "ГБУК г. Москвы "Московский выставочный зал "Галерея А3"", "district": "Центральный административный округ", "area": "район Арбат", "address": "Староконюшенный переулок, дом 39", "telephone": "(495) 697-14-56"} }

}

Запрос:

GET

http://api.example.com/v1/showrooms?limit=2&offset=1&fields=name,are a,address Ответ:

{

"status": "200",

"request": {"api": "v1", "limit": "2", "offset": "1", "fields": "name,area,address"},

"meta": {"total": "2034"},

"results": {

{"name": "ГБУК г. Москвы "Выставочный зал "Творчество"", "area": "Таганский район", "address": "Таганская улица, дом 31/22"},

{"name": "ГБУК г. Москвы "Московский выставочный зал "Галерея А3"", "area": "район Арбат", "address": "Староконюшенный переулок, дом 39"}

}

}

______________________________

*(1) NISO 2004, ISBN: 1-880124-62-9, http://www.niso.org/publications/press/UnderstandingMetadata.pdf

*(2) http://www.w3.org/DesignIssues/LinkedData.html

*(3) http://www.rfc-editor.org/rfc/rfc4180.txt

*(4) http://www.w3.org/TR/microdata/

*(5) http://www.w3.org/TR/microdata/

*(6) http://www.w3.org/TR/rdfa-syntax/, http://www.w3.org/TR/rdfa-in-html/

*(7) http://json.org/json-ru.html

*(8) http://www.w3.org/RDF/

*(9) http://www.w3.org/TR/xml11/

*(10) http://oткpытыeдaнныe.бoльшoeпpaвитeльcтвo.pф/upload/iblock/d89/d89ed3072 69b705c22da23dcbfb72c54.pdf

*(11) Пример реализации реестра приведен в Приложении 4. [2] http://www.w3.org/TR/xmlschema-0/

*(12) http://creativecommons.org/licenses/

*(13) http://opendatacommons.org/licenses/

*(14) Официальный сайт должен сохранять соответствие требованиям совместного приказа ФСБ России и ФСТЭК России от 31 августа 2010 г. N 416/489 "Об утверждении Требований о защите информации, содержащейся в информационных системах общего пользования", подготовленный во исполнение Постановления Правительства Российской Федерации от 18 мая 2009 г. N 424.

*(15) Под возможными подразумеваются альтернативные способы, что не исключает обязательный характер публикации наборов открытых государственных данных в разделе официального сайта государственного органа (далее - через свой существующий сайт) или публикацию через собственный портал открытых данных.

*(16) Общие требования к публикации реестра наборов открытых данных содержатся в п.7.1.

*(17) http ://5stardata. info

*(18) http://ckan.org/

*(19) https://drupal.org/project/dkan

*(20) Требования по машиночитаемому представлению реестра и паспортов содержатся в техническом задании на разработку портала открытых данных Российской Федерации.

*(21) В случае размещения открытых данных через портал открытых данных Российской Федерации применяется иной порядок определения требований.

*(22) Определяется в разделе 8.1.

*(23) Соответствие форматов структур и форматов наборов открытых данных приводится далее по тексту в текущем разделе.

*(24) Пример заполнения паспорта открытых данных представлен в Приложении 8.

*(25) Дата, до которой набор открытых данных содержит актуальную информацию.

*(26) В случае использования узкоспециализированных справочников, онтологий и классификаторов рекомендуется их публиковать в виде открытых данных и/или указывать ссылки их публикации (специфические типы данных).

*(27) В ряде случаев машиночитаемое представление открытых данных не является удобным вариантом для целей ознакомления с содержательной частью открытых данных потребителем.

*(28) Данные требования не являются обязательными в случае публикации наборов открытых данных через раздел открытых данных на официальном сайте государственного (муниципального) органа.

*(29) Например, данный алгоритм поддерживается в свободном файловом архиваторе 7zip (список поддерживаемых операционных систем http://www.7-zip.org/download.html).

*(30) http://www.ietf.org/rfc/rfc1738.txt

*(31) Например, недопустимо выкладывать данные с геометками, использующими закрытую систему координат.

*(32) http://www.w3.org/TR/xml11/

*(33) http://www.ietf.org/rfc/rfc1738.txt