Документация по GitHub API.
Любое обращение к API делается с помощью http-запросов к сервису api.github.com, поэтому начать изучение можно имея под рукой curl или аналогичную утилиту. Сервис возвращает ответ в формате JSON, причём немаловажное значение имеют и http-заголовки ответа. Например, информацию о пользователе можно получить, выполнив GET-запрос по URI /users/:user:
$ curl -i https://api.github.com/users/octocat
HTTP/1.1 200 OK
Server: GitHub.com
Date: Mon, 06 Oct 2014 06:18:13 GMT
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1412579893
X-GitHub-Media-Type: github.v3
{
"login": "octocat",
"id": 583231,
"avatar_url": "https://avatars.githubusercontent.com/u/583231?v=2",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
...
}
Как и ожидалось, тип содержимого ответа — это application/json. Заголовки, начинающиеся с X- не относятся к спецификации HTTP и в данном случае несут информацию, относящуюся к API сервиса:
X-GitHub-Media-Type сообщает, что используется третья версия API,
X-RateLimit-... информирует о том, каков ваш лимит на обращения к данному API.
Итак, как уже удалось выяснить, GitHub API предоставляет возможность выполнять некоторые запросы анонимно, но ограничивает количество таких обращений до 60 за час. Для того, чтобы увеличить данный лимит, требуется выполнять авторизацию. Для авторизованного клиента лимит увеличивается до 5000 обращений за час.
"Hello, GitHub!"
Регистрируемся на GitHub и создаем первый персональный ключ доступа. Можно приступать к созданию своего первого приложения.
use DDP;
use Pithub;
# Ключ доступа берем из переменной окружения
my $p = Pithub->new(
token => $ENV{GITHUB_TOKEN}
);
# Исчерпывающая информация о пользователе octocat
my $result = $p->users->get( user => 'octocat' );
# Вывод декодированной структуры ответа
p $result->content;
# Вывод количества оставшихся запросов к API
p $result->ratelimit_remaining;
Перед запуском скрипта необходимо экспортировать переменную окружения GITHUB_TOKEN, в которую нужно поместить значение ключа доступа:
$ export GITHUB_TOKEN=deadbeeffacecafe
$ perl hello_github.pl
\ {
avatar_url "https://avatars.githubusercontent.com/u/583231?v=2",
bio undef,
blog "http://www.github.com/blog",
company "GitHub",
created_at "2011-01-25T18:44:36Z",
email "octocat@github.com",
...
}
В данном примере мы создавали базовый объект Pithub $p, а затем получали доступ к методам объекта Pithub::Users с помощью метода users. Точно такой же результат можно было получить, создав Pithub::Users напрямую:
my $u = Pithub::Users->new(
token => $ENV{GITHUB_TOKEN}
);
my $result = $u->get( user => 'octocat' );
Такой же подход можно использовать и для всех других субмодулей Pithub.
Работа со списками
Некоторые вызовы API возвращают не один объект, а список JSON-объектов. Как, например, запрос списка репозиториев пользователя или организации:
use DDP;
use Pithub;
my $r = Pithub::Repos->new( token => $ENV{GITHUB_TOKEN} );
my $result = $r->list( org => 'PadreIDE' );
p $result->count;
while ( my $row = $result->next ) {
p $row->{name};
}
В данном примере запрашивается список репозиториев организации PadreIDE. Запрос возвращает список из 30 репозиториев, но самих репозиториев на самом деле 100. Связано это с тем, что GitHub по умолчанию устанавливает лимит на 30 объектов в рамках одного запроса, и для того, чтобы получить весь список объектов, можно запрашивать их постранично:
my $result = $r->list( org => 'PadreIDE' );
while ( $result && $result->success ) {
while ( my $row = $result->next ) {
p $row->{name};
}
$result = $result->next_page;
}
В данном случае метод next_page делает новый запрос к API и возвращает новую порцию данных (или undef, если данных больше нет).
Тоже самое можно получить, установив флаг auto_pagination в истинное значение, тогда метод next будет автоматически вызывать next_page при завершении списка. Кроме того, можно регулировать и количество объектов в одном ответе с помощью свойства per_page:
# включить автоматический запрос последующих страниц
$r->auto_pagination(1);
# 50 объектов на странице
$r->per_page(50);
my $result = $r->list( org => 'PadreIDE' );
while ( my $row = $result->next ) {
p $row->{name};
}
Запросы к API, которые не реализованы в Pithub
GitHub API активно развивается, добавляются новые разделы, которые не были реализованы в Pithub. Поскольку все обращения к API выполняются через http-запросы, в Pithub существует возможность указывать нужный метод и URI запроса с помощью метода request. Рассмотрим на примере Ratelimit API, которое позволяет GET-запросом по URI /rate_limit получить информацию об актуальных значениях лимитов на API-запросы для вашего приложения.
use DDP;
use Pithub;
my $p = Pithub->new(
token => $ENV{GITHUB_TOKEN}
);
my $result = $p->request(
method => 'GET',
path => '/rate_limit',
);
p $result->content;
В данном примере мы указываем метод и путь запроса к API, и в результате получаем объект класса Pithub::Result с информацией.
\ {
rate {
limit 5000,
remaining 5000,
reset 1412552655
},
resources {
core {
limit 5000,
remaining 5000,
reset 1412552655
},
search {
limit 30,
remaining 30,
reset 1412549115
}
}
}
Другой пример это Markdown API. GitHub позволяет преобразовывать данные, отправленные в формате Markdown, в html-формат.
use DDP;
use Pithub;
my $p = Pithub->new(
token => $ENV{GITHUB_TOKEN}
);
my $result = $p->request(
method => 'POST',
path => '/markdown',
data => {
text => '**Hello, World!**',
mode => 'markdown',
}
);
p $result->raw_content;
В данном примере выполняется POST-запрос, тело запроса в формате JSON формируется из структуры data. Обратите внимание, что для извлечения результата используется метод raw_content, поскольку получаемые данные приходят в формате text/html, а не application/json и не требуют декодирования.
<p><strong>Hello, World!</strong></p>
| Предыдущий урок | СОДЕРЖАНИЕ |
