Introdução à API REST

Introdução

Este artigo descreve como usar a API REST do GitHub com a GitHub CLI, curl ou JavaScript. Para ver um guia de início rápido, confira Início Rápido para a API REST do GitHub.

Sobre solicitações para a API REST

Esta seção descreve os elementos que compõem uma solicitação de API:

• Método HTTP
• Caminho
• Cabeçalhos
• Tipos de mídia
• Autenticação
• Parâmetros

Cada solicitação para a API REST inclui um método HTTP e um caminho. Dependendo do ponto de extremidade da API REST, talvez você também precise especificar cabeçalhos de solicitação, informações de autenticação, parâmetros de consulta ou parâmetros de corpo.

A documentação de referência da API REST descreve o método HTTP, o caminho e os parâmetros para cada ponto de extremidade. Ela também exibe exemplos de solicitações e respostas para cada ponto de extremidade. Para mais informações, confira a documentação de referência de REST.

Método HTTP

O método HTTP de um ponto de extremidade define o tipo de ação que ele executa em um determinado recurso. Alguns métodos HTTP comuns são GET, POST, DELETE e PATCH. A documentação de referência da API REST fornece o método HTTP para cada ponto de extremidade.

Por exemplo, o método HTTP para o ponto de extremidade "Listar problemas do repositório" é GET.

Sempre que possível, a API REST do GitHub tenta usar um método HTTP adequado para cada ação.

• GET: usado para recuperar recursos.
• POST: usado para criar recursos.
• PATCH: usado para atualizar propriedades de recursos.
• PUT: usado para substituir recursos ou coleções de recursos.
• DELETE: usado para excluir recursos.

Caminho

Cada ponto de extremidade tem um caminho. A documentação de referência da API REST fornece o caminho para cada ponto de extremidade. Por exemplo, o caminho para o ponto de extremidade "Listar problemas do repositório" é /repos/{owner}/{repo}/issues.

As chaves {} em um caminho denotam os parâmetros de caminho que precisam ser especificados por você. Os parâmetros de caminho modificam o caminho do ponto de extremidade e são necessários em sua solicitação. Por exemplo, os parâmetros de caminho para o ponto de extremidade "Listar problemas do repositório" são {owner} e {repo}. Para usar esse caminho em sua solicitação de API, substitua {repo} pelo nome do repositório no qual você deseja solicitar uma lista de problemas e substitua {owner} pelo nome da conta proprietária do repositório.

Cabeçalhos

Os cabeçalhos fornecem informações adicionais sobre a solicitação e a resposta desejada. Veja a seguir alguns exemplos de cabeçalhos que você pode usar em suas solicitações para a API REST do GitHub. Para obter um exemplo de uma solicitação que usa cabeçalhos, consulte Fazer uma solicitação.

Accept

A maioria dos pontos de extremidade da API REST do GitHub especifica que você deve transmitir um cabeçalho Accept com um valor de application/vnd.github+json. O valor do cabeçalho Accept é um tipo de mídia. Para obter mais informações sobre os tipos de mídia, confira Tipos de mídia.

X-GitHub-Api-Version

Você deve usar esse cabeçalho para especificar uma versão da API REST a ser usada para sua solicitação. Para saber mais, confira Versões da API.

User-Agent

Todas as solicitações de API precisam incluir um cabeçalho User-Agent válido. O cabeçalho User-Agent identifica o usuário ou aplicativo que está fazendo a solicitação.

Veja a seguir um exemplo de User-Agent para um aplicativo chamado Awesome-Octocat-App:

User-Agent: Awesome-Octocat-App

Solicitações sem cabeçalho User-Agent serão rejeitadas. Se você fornecer um cabeçalho User-Agent inválido, receberá uma resposta 403 Forbidden.

Tipos de mídia

Você pode especificar um ou mais tipos de mídia adicionando-os ao cabeçalho Accept de sua solicitação. Para obter mais informações sobre o cabeçalho Accept, confira Accept.

Os tipos de mídia especificam o formato dos dados que você deseja consumir da API. Os tipos de mídia são específicos aos recursos, permitindo que eles mudem de forma independente e ofereçam suporte a formatos que outros recursos não. A documentação de cada ponto de extremidade da API REST do GitHub descreverá os tipos de mídia compatíveis. Para obter mais informações, confira Documentação da API REST do GitHub.

Os tipos de mídia mais comuns compatíveis com a API REST do GitHub são application/vnd.github+json e application/json.

Existem tipos de mídia personalizados que você pode usar com alguns pontos de extremidade. A API REST, por exemplo, para gerenciar commits e pull requests, oferece suporte aos tipos de mídia diff, patch e sha. Os tipos de mídia full, raw, text ou html são usados por alguns outros pontos de extremidade.

Todos os tipos de mídia personalizados para o GitHub têm a seguinte aparência: application/vnd.github.PARAM+json, com PARAM indicando o nome do tipo de mídia. Por exemplo, para especificar o tipo de mídia raw, você poderia usar application/vnd.github.raw+json.

Para obter um exemplo de uma solicitação que usa tipos de mídia, confira Fazer uma solicitação.

Autenticação

Muitos pontos de extremidade exigem autenticação ou retornam informações adicionais se você estiver autenticado. Além disso, você pode fazer mais solicitações por hora quando estiver autenticado.

Parâmetros

Muitos métodos de API exigem ou permitem que você envie informações adicionais em parâmetros em sua solicitação. Existem alguns tipos diferentes de parâmetros: parâmetros de caminho, parâmetros de corpo e parâmetros de consulta.

Parâmetros de caminho

Os parâmetros de caminho modificam o caminho do ponto de extremidade. Esses parâmetros são obrigatórios em sua solicitação. Para obter mais informações, consulte Caminho.

Parâmetros do corpo

Os parâmetros do corpo permitem que você passe dados adicionais para a API. Esses parâmetros podem ser opcionais ou obrigatórios, dependendo do ponto de extremidade. Por exemplo, um parâmetro de corpo pode permitir que você especifique um título de problema ao criar um novo problema ou especificar determinadas configurações ao habilitar ou desabilitar um recurso. A documentação de cada ponto de extremidade da API REST do GitHub descreverá os tipos de corpo compatíveis. Para obter mais informações, confira Documentação da API REST do GitHub.

Por exemplo, o ponto de extremidade "Criar um problema" exige que você especifique um título para o novo problema em sua solicitação. Ele também permite que você especifique outras informações opcionalmente, como texto para colocar no corpo do problema, usuários para atribuir ao novo problema ou rótulos para aplicar ao novo problema. Para obter um exemplo de uma solicitação que usa parâmetros de corpo, confira Fazer uma solicitação.

Para transmitir parâmetros de corpo, você deverá autenticar sua solicitação. Para obter mais informações, confira Autenticação.

Parâmetros de consulta

Os parâmetros de consulta permitem controlar quais dados são retornados para uma solicitação. Geralmente, esses parâmetros são opcionais. A documentação de cada ponto de extremidade da API REST do GitHub descreverá quaisquer parâmetros de consulta compatíveis. Para obter mais informações, confira Documentação da API REST do GitHub.

Por exemplo, o ponto de extremidade "Listar eventos públicos" retorna trinta problemas por padrão. Você pode usar o parâmetro de consulta per_page para retornar dois problemas em vez de 30. Você pode usar o parâmetro de consulta page para buscar apenas a primeira página de resultados. Para obter um exemplo de uma solicitação que usa parâmetros de consulta, consulte Fazer uma solicitação.

Como fazer uma solicitação

gh api --method GET /octocat \
--header 'Accept: application/vnd.github+json' \
--header "X-GitHub-Api-Version: 2022-11-28"

gh api --method GET /octocat \
--header 'Accept: application/vnd.github+json' \
--header "X-GitHub-Api-Version: 2022-11-28"

gh api --method GET /events -F per_page=2 -F page=1
--header 'Accept: application/vnd.github+json' \

gh api --method GET /events -F per_page=2 -F page=1
--header 'Accept: application/vnd.github+json' \

gh api --method POST /repos/octocat/Spoon-Knife/issues \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
-f title='Created with the REST API' \
-f body='This is a test issue created by the REST API' \

gh api --method POST /repos/octocat/Spoon-Knife/issues \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
-f title='Created with the REST API' \
-f body='This is a test issue created by the REST API' \

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

Como usar a resposta

Depois que você fizer uma solicitação, a API retornará o código de status de resposta, os cabeçalhos de resposta e, possivelmente, um corpo da resposta.

Sobre o código de resposta e os cabeçalhos

Toda solicitação retornará um código de status HTTP que indica o sucesso da resposta. Para obter mais informações sobre códigos de resposta, confira a documentação do código de status de resposta HTTP do MDN.

Além disso, a resposta incluirá cabeçalhos que fornecem mais detalhes sobre a resposta. Cabeçalhos que começam com X- ou x- são personalizados para GitHub. Por exemplo, os cabeçalhos x-ratelimit-remaining e x-ratelimit-reset informam quantas solicitações você pode fazer em um período.

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/octocat/Spoon-Knife/issues \
-F per_page=2 --include

HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Cache-Control: private, max-age=60, s-maxage=60
Content-Security-Policy: default-src 'none'
Content-Type: application/json; charset=utf-8
Date: Thu, 04 Aug 2022 19:56:41 GMT
Etag: W/"a63dfbcfdb73621e9d2e89551edcf9856731ced534bd7f1e114a5da1f5f73418"
Link: <https://api.github.com/repositories/1300192/issues?per_page=1&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=1&page=14817>; rel="last"
Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin
Server: GitHub.com
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Vary: Accept, Authorization, Cookie, Accept-Encoding, Accept, X-Requested-With
X-Accepted-Oauth-Scopes: repo
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Github-Api-Version-Selected: 2022-08-09
X-Github-Media-Type: github.v3; format=json
X-Github-Request-Id: 1C73:26D4:E2E500:1EF78F4:62EC2479
X-Oauth-Client-Id: 178c6fc778ccc68e1d6a
X-Oauth-Scopes: gist, read:org, repo, workflow
X-Ratelimit-Limit: 15000
X-Ratelimit-Remaining: 14996
X-Ratelimit-Reset: 1659645499
X-Ratelimit-Resource: core
X-Ratelimit-Used: 4
X-Xss-Protection: 0

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`)
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`)
}

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--include

HTTP/2 200
server: GitHub.com
date: Thu, 04 Aug 2022 20:07:51 GMT
content-type: application/json; charset=utf-8
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With
etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18"
x-github-media-type: github.v3; format=json
link: <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=7409>; rel="last"
access-control-expose-headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
x-ratelimit-limit: 15000
x-ratelimit-remaining: 14996
x-ratelimit-reset: 1659645535
x-ratelimit-resource: core
x-ratelimit-used: 4
accept-ranges: bytes
content-length: 4936
x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715

Sobre o corpo da resposta

Muitos pontos de extremidade devolverão um corpo da resposta. A menos que especificado de outra forma, o corpo da resposta está no formato JSON. Os campos em branco são incluídos como null em vez de serem omitidos. Todos os carimbo de data/hora são devolvidos no formato UTC, ISO 8601: YYYY-MM-DDTHH:MM:SSZ.

Ao contrário da API do GraphQL, onde você especifica quais informações quer, a API REST normalmente retorna mais informações do que você precisa. Se desejar, você pode analisar a resposta a fim de extrair informações específicas.

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/REPO-OWNER/REPO-NAME/issues \
-F per_page=2 > data.json

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/REPO-OWNER/REPO-NAME/issues \
-F per_page=2 > data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

Declarações detalhadas vs. resumidas

Uma resposta pode incluir todos os atributos de um recurso ou apenas um subconjunto de atributos, dependendo de você efetuar fetch de um recurso individual ou de uma lista de recursos.

• Quando você efetuar fetch de um recurso individual, como um repositório específico, a resposta normalmente incluirá todos os atributos desse recurso. Esta é a representação "detalhada" do recurso.
• Quando você efetuar fetch de uma lista de recursos, como uma lista de vários repositórios, a resposta incluirá apenas um subconjunto dos atributos para cada recurso. Esta é a representação "resumo" do recurso.

Observe que às vezes a autorização influencia a quantidade de detalhes incluídos em uma declaração.

A razão para isso é que alguns atributos são computacionalmente caros para a API fornecer, portanto, o GitHub exclui esses atributos da declaração resumida. Para obter esses atributos, você pode efetuar fetch da declaração detalhada.

A documentação fornece um exemplo de resposta para cada método da API. A resposta de exemplo ilustra todos os atributos que retornados por esse método.

Hipermídia

Todos os recursos podem ter uma ou mais propriedades *_url vinculando outros recursos. Estes tem o objetivo de fornecer URLs explícitas para que os clientes API apropriados não precisem construir URLs por conta própria. É altamente recomendável que os clientes da API os utilizem. Fazer isso tornará as futuras atualizações da API mais fáceis para os desenvolvedores. Espera-se que todas as URLs sejam modelos de URI RFC 6570 adequados.

Em seguida, você pode expandir esses modelos usando algo como ogem 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"

Próximas etapas

Este artigo demonstrou como listar e criar problemas em um repositório. Para obter mais práticas, tente comentar um problema, editar o título de um problema ou fechar um problema. Para obter mais informações, consulte o ponto de extremidade "Criar um comentário sobre o problema" e o ponto de extremidade "Atualizar um problema".

Para obter mais informações sobre outros pontos de extremidade que você pode usar, confira a documentação de referência de REST.