Ресурсы в REST API

Схема

Доступ к API осуществляется с http(s)://HOSTNAME/api/v3. Все данные отправляются и получаются в формате JSON.

$ curl -I http(s)://<em>HOSTNAME</em>/api/v3/users/octocat/orgs

> HTTP/2 200
> Server: nginx
> Date: Fri, 12 Oct 2012 23:33:14 GMT
> Content-Type: application/json; charset=utf-8
> ETag: "a00049ba79152d03380c34652f2cb612"
> X-GitHub-Media-Type: github.v3
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4987
> x-ratelimit-reset: 1350085394
> X-GitHub-Enterprise-Version: 3.8.0
> Content-Length: 5
> Cache-Control: max-age=0, private, must-revalidate
> X-Content-Type-Options: nosniff

Пустые поля включаются как null, а не пропускаются.

Все метки времени возвращаются в формате UTC ISO 8601:

YYYY-MM-DDTHH:MM:SSZ

Дополнительные сведения о часовых поясах в метках времени см. в этом разделе.

Сводные представления

При получении списка ресурсов в ответ включается подмножество атрибутов ресурса. Это "сводное" представление ресурса. (Предоставление некоторых атрибутов интерфейсом API требует больших вычислительных затрат. По соображениям производительности такие атрибуты исключаются из сводного представления. Чтобы получить эти атрибуты, запросите "подробное" представление.)

Пример. При запросе списка репозиториев вы получаете сводное представление каждого репозитория. Здесь мы получаем список репозиториев, принадлежащих организации octokit:

GET /orgs/octokit/repos

Подробные представления

При получении отдельного ресурса в ответ обычно включаются все его атрибуты. Это "подробное" представление ресурса. (Обратите внимание, что авторизация иногда влияет на объем сведений, включаемых в представление.)

Пример. При получении отдельного репозитория вы получаете его подробное представление. Здесь мы получаем репозиторий octokit/octokit.rb:

GET /repos/octokit/octokit.rb

В документации приводится пример ответа для каждого метода API. В примере ответа показаны все атрибуты, возвращаемые этим методом.

Проверка подлинности

GitHub рекомендует создать маркер для проверки подлинности в REST API. Дополнительные сведения о том, какой тип токена необходимо создать, см. в разделе "Проверка подлинности в REST API".

Вы можете выполнить проверку подлинности запроса, отправив маркер в заголовке Authorization запроса:

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"

Если вы пытаетесь использовать конечную точку REST API без маркера или маркера, имеющего недостаточно разрешений, вы получите 404 Not Found или 403 Forbidden ответ.

Ключ и секрет OAuth2

curl -u my_client_id:my_client_secret 'http(s)://<em>HOSTNAME</em>/api/v3/user/repos'

Используя ваш client_id и client_secret не прошедший проверку подлинности в качестве пользователя, он будет определять только OAuth app для увеличения ограничения скорости. Разрешения предоставляются только пользователям, а не приложениям, и вы сможете получить только те данные, которые доступны пользователю, не прошедшему проверку подлинности. Не утечь данные для пользователей.

Вы не сможете пройти проверку подлинности с помощью ключа и секрета OAuth2 в закрытом режиме. При попытке сделать это будет возвращена ошибка 401 Unauthorized. Дополнительные сведения см. в разделе "Включение частного режима".

Максимальное количество неудачных попыток входа

При попытке пройти проверку подлинности с недействительными учетными данными возвращается ошибка 401 Unauthorized.

$ curl -I http(s)://<em>HOSTNAME</em>/api/v3 --header "Authorization: Bearer INVALID-TOKEN"
> HTTP/2 401

> {
>   "message": "Bad credentials",
>   "documentation_url": "https://docs.github.com/enterprise/3.8/rest"
> }

Если за небольшой промежуток времени было обнаружено несколько запросов с недействительными учетными данными, API станет временно отклонять все попытки проверки подлинности со стороны данного пользователя (в том числе с действительными учетными данными) с ошибкой 403 Forbidden:

> HTTP/2 403
> {
>   "message": "Maximum number of login attempts exceeded. Please try again later.",
>   "documentation_url": "https://docs.github.com/enterprise/3.8/rest"
> }

Параметры

Многие методы API принимают необязательные параметры. Для запросов GET любые параметры, не указанные в виде сегмента пути, можно передать в качестве параметра строки HTTP-запроса:

curl -i "http(s)://<em>HOSTNAME</em>/api/v3/repos/vmg/redcarpet/issues?state=closed"

В этом примере значения vmg и redcarpet предоставляются для параметров :owner и :repo в пути, а :state передается в строке запроса.

Для запросов POST, PATCH, PUT и DELETE параметры, не включенные в URL-адрес, должны быть закодированы как JSON, причем заголовок Content-Type должен иметь значение application/json:

curl -i --header "Authorization: Bearer YOUR-TOKEN" -d '{"scopes":["repo_deployment"]}' http(s)://<em>HOSTNAME</em>/api/v3/authorizations

Корневая конечная точка

Вы можете отправить запрос GET к корневой конечной точке, чтобы получить все категории конечных точек, поддерживаемые REST API:

$ curl -u USERNAME:PASSWORD http(s)://<em>HOSTNAME</em>/api/v3

Идентификаторы глобальных узлов GraphQL

Дополнительные сведения о том, как найти node_ids через REST API и использовать их в операциях GraphQL, см. в руководстве по autoTITLE.

HTTP-команды

Везде, где это возможно, REST API GitHub Enterprise Server использует специальные HTTP-команды для каждого действия. Обратите внимание, что HTTP-команды указываются с учетом регистра.

Команда	Description
HEAD	Может быть выполнена для любого ресурса с целью получить только данные заголовка HTTP.
GET	Используется для получения ресурсов.
POST	Используется для создания ресурсов.
PATCH	Используется для обновления ресурсов с частичными данными JSON. Например, ресурс Issue имеет атрибуты title и body. Запрос PATCH может принимать один или несколько атрибутов для обновления ресурса.
PUT	Используется для замены ресурсов или коллекций. Для запросов PUT без атрибута body обязательно установите для заголовка Content-Length нулевое значение.
DELETE	Используется для удаления ресурсов.

Гиперсреда

Любой ресурс может иметь одно или несколько свойств *_url, содержащих ссылки на другие ресурсы. Они предназначены для предоставления явных URL-адресов, чтобы соответствующим клиентам API не приходилось формировать URL-адреса самостоятельно. Настоятельно рекомендуется, чтобы клиенты API использовали эти свойства. Так разработчикам будет проще обновлять API в будущем. Все URL-адреса должны соответствовать шаблонам URI RFC 6570.

Затем можно расширить эти шаблоны, например, с помощью пакета uri_template:

>> tmpl = URITemplate.new('/notifications{?since,all,participating}')
>> tmpl.expand
=> "/notifications"

>> tmpl.expand all: 1
=> "/notifications?all=1"

>> tmpl.expand all: 1, participating: 1
=> "/notifications?all=1&participating=1"

Предоставление общего доступа к ресурсам независимо от источника

API поддерживает общий доступ к ресурсам независимо от источника (CORS) для запросов AJAX из любого источника. Вы можете ознакомиться с рекомендацией консорциума W3C в отношении CORS или этим введением из руководства по безопасности HTML 5.

Вот пример запроса, отправляемого из браузера на http://example.com:

$ curl -I http(s)://<em>HOSTNAME</em>/api/v3 -H "Origin: http://example.com"
HTTP/2 302
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval

Вот как выглядит предварительный запрос CORS:

$ curl -I http(s)://<em>HOSTNAME</em>/api/v3 -H "Origin: http://example.com" -X OPTIONS
HTTP/2 204
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-GitHub-OTP, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Max-Age: 86400

Обратные вызовы JSON-P

Вы можете передать параметр ?callback в любой вызов GET, чтобы результаты были заключены в функцию JSON. Обычно такой способ применяется, когда содержимое GitHub Enterprise Server должно внедряться на веб-страницы в браузерах путем обхода проблем с доступом между доменами. Ответ включает те же выходные данные, что и при обычном вызове API, а также соответствующие сведения о заголовках HTTP.

$ curl http(s)://<em>HOSTNAME</em>/api/v3?callback=foo

> /**/foo({
>   "meta": {
>     "status": 200,
>     "x-ratelimit-limit": "5000",
>     "x-ratelimit-remaining": "4966",
>     "x-ratelimit-reset": "1372700873",
>     "Link": [ // pagination headers and other links
>       ["http(s)://<em>HOSTNAME</em>/api/v3?page=2", {"rel": "next"}]
>     ]
>   },
>   "data": {
>     // the data
>   }
> })

Вы можете написать обработчик JavaScript для обработки обратного вызова. Вот минимальный пример, который можно опробовать:

<html>
<head>
<script type="text/javascript">
function foo(response) {
  var meta = response.meta;
  var data = response.data;
  console.log(meta);
  console.log(data);
}

var script = document.createElement('script');
script.src = 'http(s)://HOSTNAME/api/v3?callback=foo';

document.getElementsByTagName('head')[0].appendChild(script);
</script>
</head>

<body>
  <p>Open up your browser's console.</p>
</body>
</html>

Все заголовки имеют те же строковые значения, что и заголовки HTTP, с одним существенным исключением: Link. Заголовки Link предварительно анализируются и передаются в виде массива кортежей [url, options].

Следующая ссылка:

Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"

...будет выглядеть следующим образом в выходных данных обратного вызова:

{
  "Link": [
    [
      "url1",
      {
        "rel": "next"
      }
    ],
    [
      "url2",
      {
        "rel": "foo",
        "bar": "baz"
      }
    ]
  ]
}

Часовые пояса

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

• Явное предоставление метки времени ISO 8601 со сведениями о часовом поясе
• Использование заголовка Time-Zone
• Использование последнего известного часового пояса для пользователя
• Использование UTC по умолчанию при отсутствии других сведений о часовом поясе

Обратите внимание, что эти правила применяются только к данным, передаваемым в API, а не к данным, возвращаемым API. Как упоминалось в разделе Схема, метки времени, возвращаемые API, имеют формат UTC ISO 8601.

Явное предоставление метки времени ISO 8601 со сведениями о часовом поясе

Для вызовов API, позволяющих указать метку времени, мы используем такую метку времени. Примером этого является API для управления фиксациями. Дополнительные сведения см. в разделе «AUTOTITLE».

Метки времени выглядят примерно так: 2014-02-27T15:05:06+01:00. Пример указания меток времени также см. здесь.

Использование заголовка Time-Zone

Можно указать заголовок Time-Zone, который определяет часовой пояс в соответствии со списком имен из базы данных Olson.

curl -H "Time-Zone: Europe/Amsterdam" -X POST http(s)://<em>HOSTNAME</em>/api/v3/repos/github-linguist/linguist/contents/new_file.md

Это означает, что мы создаем метку времени для момента времени, когда выполняется вызов API, в часовом поясе, определенном в этом заголовке. Например, API для управления содержимым создает фиксацию Git для каждого добавления или изменения и использует текущее время в качестве метки времени. Дополнительные сведения см. в разделе «AUTOTITLE». В этом заголовке определяется часовой пояс, используемый для создания текущей метки времени.

Использование последнего известного часового пояса для пользователя

Если заголовок Time-Zone не указан и вы выполняете вызов API с проверкой подлинности, мы используем последний известный часовой пояс для пользователя, прошедшего проверку подлинности. Последний известный часовой пояс обновляется при каждом посещении веб-сайта GitHub Enterprise Server.

Использование UTC по умолчанию при отсутствии других сведений о часовом поясе

Если получить сведения о часовом поясе указанными выше способами не удалось, мы используем UTC в качестве часового пояса для создания фиксации Git.