Начальное руководство для журналистов, которые хотят разбираться в API документации

HowTo Открытые данные Перевод

api

Слово API гуляет по медиасреде уже последние несколько лет. Расшифровывается это как «интерфейс программирования приложений». API дает возможность компьютерным программам взаимодействовать друг с другом различными способами и позволяет им обмениваться между собой данными.

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

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

Основной вопрос: Что мне может дать этот интерфейс?

Поищите в интернете упоминание слова “requests”. Если вы ничего не нашли, то попробуйте отыскать слова “REST API” или нечто похожее на последнюю часть URL.

В этих разделах обратите внимание на слова “get” и “post”. Они называются методами, которые могут быть выполнены определенными действиями API. (Некоторые разработчики могут называть их функциями, но мы все же будем использовать термин «методы»).

Если документация написана простым языком, не составит особого труда понять, какой метод выполняется. В ином случае, чтобы определить метод, вам придется найти кого-нибудь с большим опытом программирования. Но помните:

“Get” отправляет запрос на сервер API. Например, GET (получить) количество упоминаний определенного адреса в базе данных.

“Post” изменяет базу данных, создавая, дополняя или перемещая информацию. Например, POST (добавить) новый адрес в базу данных.

В каком формате я могу получить данные?

Обычно API позволяет выбирать вид данных, эта функция также известна под названием «формат ответа». Вы увидите либо “json”, либо “XML”. Иногда можно встретить “txt” или иные форматы. Лучший формат определяется разработчиком, но, как минимум, вы будете знать, какие из них доступны.

Чтобы найти опции формата, ищите слова «format» или «response». Иногда он упоминается в начале документации, иногда «format» можно найти в методах.

Что требуется взамен на получение нужных мне данных?

Иногда можно осуществить запрос к API инкогнито. Но создатели API зачастую хотят знать, как и кем он используется. В дополнение, они хотят предотвратить перегрузку сервера и избавиться от выходок разработчиков, поэтому во многих запросах к API требуется уникальный ID человека или программы, которые делают запрос.

Получение такого ключа обычно не вызывает затруднений. Найдите слово «аутентификация» или «ключ API», чтобы получить дальнейшие инструкции и узнать, какой из методов требует аутентификации.

Могу я протестировать запросы к API, даже если я не разработчик?

Да. Вы можете создать свой собственный тестовый запрос, скопировав пример ответа в методе и изменив переменные (как правило, их называют «параметрами»).

Например, попробуем найти в обзорах New York Times информацию о фильмах из серии «Гарри Поттер» в формате XML. Воспользуйтесь любой поисковой системой, которая вам нравится, чтобы найти The New York Times movie reviews API. Этот API не идеален (в любом случае, это просто бета-версия). Алгоритм, который мы опишем, вполне можно сократить, когда у вас появится больше опыта, но для первого раза мы пойдем длинным путем.

Итак, мы на странице API:

1. Найдите то, что поможет вам получить обзор с помощью ключевых слов. В данном случае, это метод “Reviews by Keyword”. Внутри есть описание с примером URI (он выделен темно-серым цветом). Это шаблон вашего запроса.

Скопируйте его и вставьте  в текстовый редактор [TextWrangler (Mac), TextMate (Mac) или TextPad (Windows)]. Теперь можно изменять параметры, т.е. значения в скобках. Для удобства они выделены полужирным шрифтом.

В этом методе два обязательных параметра: version, т.е. версия API (v2), и ключ API, который можно получить здесь.

Исходный вид:

http://api.nytimes.com/svc/movies/{version}/reviews/search[.response_format]?[optional-param1=value1]&[…]&api-key={your-API-key}

Результат:

http://api.nytimes.com/svc/movies/v2/reviews/search[.response_format]?[optional-param1=value1]&[…]&api-key={paste your API key and here and delete the surrounding braces}

2. Затем введем два дополнительных параметра, которые описаны чуть ниже в этом же разделе Movie Reviews API documentation:

  • Формат ответа, а именно: .xml
  • Ключевое слово запроса: “Potter” (Поиск словосочетания “Harry+Potter” работать не будет. По крайней мере, в бета-версии).
  • В результате мы получим диапазон данных, начиная с первого фильма до последнего. Как сказано в документации, формат диапазона: YYYY-MM-DD;YYYY-MM-DD. Поэтому введем следующие параметры: opening-date=2001-11-01;2011-07-31.

Теперь ваш пример URI должен выглядеть так (новые параметры выделены):

http://api.nytimes.com/svc/movies/v2/reviews/search.xml?&query=Potter&opening-date=2001-11-01;2011-07-31&api-key={paste your API key and delete the surrounding French braces}

3. Скопируйте то, что получилось и вставьте в адресную строку браузера.

Если все сделано правильно, вы получите следующий ответ. На самом деле, если хотите, можете скопировать все, что стоит перед знаками “={“, вставить в адресную строку, а в конце прибавить свой API ключ. Так вы получите ответ в формате XML.

Вуаля! Вы только создали сой первый API запрос и получили обзоры фильмов “Гарри Поттер”.

Некоторые замечательные разработчики создают также консоль, сэндбокс и пустые формы для заполнения. Это позволяет протестировать ваш запрос без написания его вручную. А еще лучше, инструменты, которые грамотно генерируют и запрос, и результат. Вы и ваш разработчик можете скопировать их и использовать, как пожелаете.

Вы натолкнетесь на огромное количество стилей документации, когда начнете искать подходящий вариант. Если у вас есть вопросы по поводу того, что вы нашли, не стесняйтесь, задавайте их на  Hacks/Hackers help board.

Крис Ву – журналист, стратег, программист и повар. Когда она не занимается консультацией клиентов по вопросам привлечения пользователей и создания сообществ, она организует встречи на  Hacks/Hackers, где собираются журналисты, разработчики и дизайнеры для того, чтобы перезапустить новости. Ее твиттер: @MacDiva.