{"meta":{"title":"Introdução à API REST","intro":"Saiba como usar a GitHub API REST.","product":"API REST","breadcrumbs":[{"href":"/pt/rest","title":"API REST"},{"href":"/pt/rest/using-the-rest-api","title":"Usando a API REST"},{"href":"/pt/rest/using-the-rest-api/getting-started-with-the-rest-api","title":"Introdução"}],"documentType":"article"},"body":"# Introdução à API REST\n\nSaiba como usar a GitHub API REST.\n\n## Introdução\n\nEste artigo descreve como usar a GitHub API REST com GitHub CLI, `curl`ou JavaScript. Para ver um guia de início rápido, confira [Início Rápido da API REST GitHub](/pt/rest/quickstart).\n\n\n\n
\n\n## Sobre solicitações para a API REST\n\nEsta seção descreve os elementos que compõem uma solicitação de API:\n\n* [Método HTTP](#http-method)\n* [Caminho](#path)\n* [Cabeçalhos](#headers)\n* [Tipos de mídia](#media-types)\n* [Autenticação](#authentication)\n* [Parâmetros](#parameters)\n\nCada 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.\n\nA 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](/pt/rest).\n\n### método HTTP\n\nO 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.\n\nPor exemplo, o método HTTP para o [ponto de extremidade \"Listar problemas do repositório\"](/pt/rest/issues/issues#list-repository-issues) é `GET`.\n\nSempre que possível, a GitHub API REST se esforça para usar um método HTTP apropriado para cada ação.\n\n* `GET`: usado para recuperar recursos.\n* `POST`: usado para criar recursos.\n* `PATCH`: usado para atualizar propriedades de recursos.\n* `PUT`: usado para substituir recursos ou coleções de recursos.\n* `DELETE`: usado para excluir recursos.\n\n### Caminho\n\nCada 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\"](/pt/rest/issues/issues#list-repository-issues) é `/repos/{owner}/{repo}/issues`.\n\nAs 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\"](/pt/rest/issues/issues#list-repository-issues) 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.\n\n### Cabeçalhos\n\nOs cabeçalhos fornecem informações adicionais sobre a solicitação e a resposta desejada. A seguir estão alguns exemplos de cabeçalhos que você pode usar em suas solicitações para a GitHub API REST. Para obter um exemplo de uma solicitação que usa cabeçalhos, consulte [Fazer uma solicitação](#making-a-request).\n\n#### `Accept`\n\nA maioria dos GitHub pontos de extremidade da API REST especifica que você deve passar um cabeçalho `Accept` com o valor `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](#media-types).\n\n#### `X-GitHub-Api-Version`\n\nVocê 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](/pt/rest/overview/api-versions).\n\n#### `User-Agent`\n\nTodas 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.\n\n\n\nPor padrão, GitHub CLI envia um cabeçalho `User-Agent` válido. No entanto, GitHub recomenda usar seu nome de usuário GitHub ou o nome do seu aplicativo como valor do cabeçalho `User-Agent`. Isso permite GitHub entrar em contato com você se houver problemas.\n\n
\n\n\n\nPor padrão, `curl` envia um cabeçalho `User-Agent` válido. No entanto, GitHub recomenda usar o seu GitHub nome de usuário ou o nome do seu aplicativo para o valor do cabeçalho `User-Agent`. Isso permite GitHub entrar em contato com você se houver problemas.\n\n
\n\n\n\nSe você usar o SDK Octokit.js, o SDK enviará um cabeçalho `User-Agent` válido para você. No entanto, GitHub recomenda usar seu nome de usuário GitHub ou o nome do seu aplicativo como valor do cabeçalho `User-Agent`. Isso permite GitHub entrar em contato com você se houver problemas.\n\n
\n\nVeja a seguir um exemplo de `User-Agent` para um aplicativo chamado `Awesome-Octocat-App`:\n\n```shell\nUser-Agent: Awesome-Octocat-App\n```\n\nSolicitações sem cabeçalho `User-Agent` serão rejeitadas. Se você fornecer um cabeçalho `User-Agent` inválido, receberá uma resposta `403 Forbidden`.\n\n\n\n\n\n### Tipos de mídia\n\nVocê 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`](#accept).\n\nOs 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 GitHub ponto de extremidade da API REST descreverá os tipos de mídia aos quais ele dá suporte. Para obter mais informações, confira [documentação da API REST GitHub](/pt/rest).\n\nOs tipos de mídia mais comuns compatíveis com a GitHub API REST são `application/vnd.github+json` e `application/json`.\n\nExistem tipos de mídia personalizados que você pode usar com alguns endpoints. A API REST, por exemplo, para gerenciar [commits](/pt/rest/commits/commits#get-a-commit) e [pull requests](/pt/rest/pulls/pulls), 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 outros endpoints.\n\nTodos os tipos de mídia personalizados para GitHub têm a seguinte aparência: `application/vnd.github.PARAM+json`, onde `PARAM` é 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`.\n\nPara obter um exemplo de uma solicitação que usa tipos de mídia, confira [Fazer uma solicitação](#making-a-request).\n\n### Autenticação\n\nMuitos endpoints 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.\n\n\n\nPara autenticar sua solicitação, você precisará fornecer um token de autenticação com os escopos ou as permissões necessários. Há algumas maneiras diferentes de obter um token: você pode criar um personal access token, gerar um token com um GitHub App ou usar o recurso interno `GITHUB_TOKEN` em um fluxo de trabalho GitHub Actions. Para saber mais, confira [Autenticação na API REST](/pt/rest/overview/authenticating-to-the-rest-api).\n\nPara obter um exemplo de uma solicitação que usa um token de autenticação, confira [Fazer uma solicitação](#making-a-request).\n\n> \\[!NOTE]\n> Se você não quiser criar um token, poderá usar GitHub CLI.\n> GitHub CLI cuidará da autenticação para você e ajudará a manter sua conta segura. Para obter mais informações, consulte a [GitHub CLI versão desta página](/pt/rest/guides/getting-started-with-the-rest-api?tool=cli).\n\n> \\[!WARNING]\n> Trate seu token de acesso da mesma forma que trataria suas senhas ou outras credenciais confidenciais. Para saber mais, confira [Manter suas credenciais de API seguras](/pt/rest/overview/keeping-your-api-credentials-secure).\n\n
\n\n\n\nEmbora alguns pontos de extremidade da API REST estejam acessíveis sem autenticação, GitHub CLI requer que você se autentique antes de usar o `api` subcomando para fazer uma solicitação de API. Use o `auth login` subcomando para autenticar em GitHub. Para saber mais, confira [Fazer uma solicitação](#making-a-request).\n\n
\n\n\n\nPara autenticar sua solicitação, você precisará fornecer um token de autenticação com os escopos ou as permissões necessários. Há algumas maneiras diferentes de obter um token: você pode criar um personal access token, gerar um token com um GitHub App ou usar o recurso interno `GITHUB_TOKEN` em um fluxo de trabalho GitHub Actions. Para saber mais, confira [Autenticação na API REST](/pt/rest/overview/authenticating-to-the-rest-api).\n\nPara obter um exemplo de uma solicitação que usa um token de autenticação, confira [Fazer uma solicitação](#making-a-request).\n\n> \\[!WARNING]\n> Trate seu token de acesso da mesma forma que trataria suas senhas ou outras credenciais confidenciais. Para saber mais, confira [Manter suas credenciais de API seguras](/pt/rest/overview/keeping-your-api-credentials-secure).\n\n
\n\n### Parâmetros\n\nMuitos 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.\n\n#### Parâmetros de caminho\n\nOs parâmetros de caminho modificam o caminho do endpoint. Esses parâmetros são obrigatórios em sua solicitação. Para obter mais informações, consulte [Caminho](#path).\n\n#### Parâmetros do corpo\n\nOs 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 GitHub endpoint da API REST descreverá os parâmetros de corpo suportados. Para obter mais informações, confira [documentação da API REST GitHub](/pt/rest).\n\nPor exemplo, o [endpoint \"Criar uma questão\"](/pt/rest/issues/issues#create-an-issue) exige que você especifique um título para a nova questão 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](#making-a-request).\n\nPara transmitir parâmetros de corpo, você deverá autenticar sua solicitação. Para obter mais informações, confira [Autenticação](#authentication).\n\n#### Parâmetros de consulta\n\nOs 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 GitHub descreverá os parâmetros de consulta que ele permita. Para obter mais informações, confira [documentação da API REST GitHub](/pt/rest).\n\nPor exemplo, o [endpoint \"List public events\"](/pt/rest/activity/events#list-public-events) retorna trinta itens 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](#making-a-request).\n\n## Como fazer uma solicitação\n\n\n\nEsta seção demonstra como fazer uma solicitação autenticada para a GitHub API REST usando GitHub CLI.\n\n### 1. Instalação\n\nInstale GitHub CLI no macOS, Windows ou Linux. Para obter mais informações, consulte [Instalação](https://github.com/cli/cli#installation) no GitHub CLI repositório.\n\n### 2. Autenticar\n\n1. Para autenticar no GitHub, execute o seguinte comando no seu terminal.\n\n ```shell\n gh auth login\n ```\n\n Você pode usar a opção `--scopes` para especificar os escopos desejados. Se você quiser autenticar com um token criado, poderá usar a opção `--with-token`. Para obter mais informações, consulte a [GitHub CLI`auth login` documentação](https://cli.github.com/manual/gh_auth_login).\n\n2. Selecione o local em que deseja se autenticar:\n\n * Se você acessar GitHub em GitHub.com, selecione **GitHub.com**.\n * Se você acessar GitHub em um domínio diferente, selecione **Outro** e, em seguida, insira seu nome de host (por exemplo: `octocorp.ghe.com`).\n\n3. Siga o restante das solicitações na tela.\n\nGitHub CLI armazena automaticamente suas credenciais do Git para você quando você escolhe HTTPS como seu protocolo preferencial para operações git e responde \"sim\" ao prompt perguntando se você gostaria de autenticar no Git com suas GitHub credenciais. Isso pode ser útil porque permite que você use comandos Git como `git push` e `git pull` sem a necessidade de configurar um gerenciador de credenciais distinto ou usar SSH.\n\n### 3. Escolha um endpoint para sua solicitação\n\n1. Escolha um ponto de extremidade para o qual fazer uma solicitação. Você pode explorar a GitHub de [](/pt/rest) para descobrir endpoints que você pode usar para interagir com GitHub.\n\n2. Identifique o método HTTP e o caminho do ponto de extremidade. Você enviará tais informações com sua solicitação. Para obter mais informações, consulte [Método HTTP](#http-method) e [Caminho](#path).\n\n Por exemplo, o [ponto de extremidade \"Criar um problema\"](/pt/rest/issues/issues#create-an-issue) usa o método HTTP `POST` e o caminho `/repos/{owner}/{repo}/issues`.\n\n3. Identifique os parâmetros de caminho necessários. Os parâmetros de caminho necessários aparecem entre colchetes `{}` no caminho do ponto de extremidade. Substitua cada marcador de posição do parâmetro pelo valor desejado. Para obter mais informações, consulte [Caminho](#path).\n\n Por exemplo, o [ponto de extremidade \"Criar um problema\"](/pt/rest/issues/issues#create-an-issue) usa o caminho `/repos/{owner}/{repo}/issues` e os parâmetros de caminho são `{owner}` e `{repo}`. Para usar esse caminho em sua solicitação de API, substitua `{repo}` pelo nome do repositório no qual deseja criar um novo problema e substitua `{owner}` pelo nome da conta proprietária do repositório.\n\n### 4. Fazer uma solicitação com GitHub CLI\n\nUse o GitHub CLI`api` subcomando para fazer sua solicitação de API. Para obter mais informações, consulte a [GitHub CLI`api` documentação](https://cli.github.com/manual/gh_api).\n\nEm sua solicitação, especifique as seguintes opções e valores:\n\n* **--method** seguido pelo método HTTP e o caminho do endpoint. Para obter mais informações, consulte [Método HTTP](#http-method) e [Caminho](#path).\n* **--header**:\n * **`Accept`:** passe o tipo de mídia em um cabeçalho `Accept`. Para transmitir vários tipos de mídia em um cabeçalho `Accept`, separe os tipos de mídia com uma vírgula: `Accept: application/vnd.github+json,application/vnd.github.diff`. Para obter mais informações, confira [`Accept`](#accept) e [Tipos de mídia](#media-types).\n * **`X-GitHub-Api-Version`:** passe a versão da API em um cabeçalho `X-GitHub-Api-Version`. Para obter mais informações, consulte [`X-GitHub-Api-Version`](#x-github-api-version).\n* **`-f`** ou **`-F`** seguido por quaisquer parâmetros de corpo ou parâmetros de consulta no formato `key=value`. Use a opção `-F` para transmitir um parâmetro que seja um número, booliano ou nulo. Use a opção `-f` para transmitir parâmetros de sequência.\n\n Alguns pontos de extremidade usam parâmetros de consulta que são matrizes. Para enviar uma matriz na cadeia de caracteres de consulta, use o parâmetro de consulta uma vez por item de matriz e acrescente `[]` após o nome do parâmetro de consulta. Por exemplo, para fornecer uma matriz de dois IDs de repositório, use `-f repository_ids[]=REPOSITORY_A_ID -f repository_ids[]=REPOSITORY_B_ID`.\n\n Se você não precisar especificar nenhum parâmetro de corpo ou parâmetro de consulta em sua solicitação, omita essa opção. Para obter mais informações, consulte [Parâmetros de corpo](#body-parameters) e [Parâmetros de consulta](#query-parameters). Para obter exemplos, confira [Solicitação de exemplo usando parâmetros de corpo](#example-request-using-body-parameters) e [Solicitação de exemplo usando parâmetros de consulta](#example-request-using-query-parameters).\n\n#### Solicitação de exemplo\n\nA solicitação de exemplo a seguir usa o [ponto de extremidade \"Obter Octocat\"](/pt/rest/meta/meta#get-octocat) para retornar o octocat como arte ASCII.\n\n```shell copy\ngh api --method GET /octocat \\\n--header 'Accept: application/vnd.github+json' \\\n--header \"X-GitHub-Api-Version: 2022-11-28\"\n```\n\n#### Exemplo de solicitação usando parâmetros de consulta\n\nO [endpoint \"Listar eventos públicos\"](/pt/rest/activity/events#list-public-events) retorna trinta questões por padrão. O exemplo a seguir usa o parâmetro de consulta `per_page` para retornar dois problemas em vez de 30 e o parâmetro de consulta `page` para efetuar fetch apenas na primeira página de resultados.\n\n```shell copy\ngh api --method GET /events -F per_page=2 -F page=1\n--header 'Accept: application/vnd.github+json' \\\n```\n\n#### Exemplo de solicitação usando parâmetros do corpo\n\nO exemplo a seguir usa o [ponto de extremidade \"Criar um problema\"](/pt/rest/issues/issues#create-an-issue) para criar um novo problema em um repositório the octocat/Spoon-Knife. Na resposta, localize o `html_url` do seu problema e acesse-o no navegador.\n\n```shell copy\ngh api --method POST /repos/octocat/Spoon-Knife/issues \\\n--header \"Accept: application/vnd.github+json\" \\\n--header \"X-GitHub-Api-Version: 2022-11-28\" \\\n-f title='Created with the REST API' \\\n-f body='This is a test issue created by the REST API' \\\n```\n\n
\n\n\n\nEsta seção demonstra como fazer uma solicitação autenticada para a GitHub API REST usando `curl`.\n\n### 1. Instalação\n\nVocê precisa ter o `curl` instalado no seu computador. Para verificar se o `curl` já está instalado, execute `curl --version` na linha de comando.\n\n* Se a saída exibir informações sobre a versão do `curl`, o `curl` está instalado.\n* Se você receber uma mensagem semelhante a `command not found: curl`, o `curl` não está instalado. Baixe e instale o `curl`. Para obter mais informações, confira a [página de download do curl](https://curl.se/download.html).\n\n### 2. Escolha um ponto de extremidade para sua solicitação\n\n1. Escolha um ponto de extremidade para o qual fazer uma solicitação. Você pode explorar a GitHub de [](/pt/rest) para descobrir endpoints que você pode usar para interagir com GitHub.\n\n2. Identifique o método HTTP e o caminho do ponto de extremidade. Você enviará tais informações com sua solicitação. Para obter mais informações, consulte [Método HTTP](#http-method) e [Caminho](#path).\n\n Por exemplo, o [ponto de extremidade \"Criar um problema\"](/pt/rest/issues/issues#create-an-issue) usa o método HTTP `POST` e o caminho `/repos/{owner}/{repo}/issues`.\n\n3. Identifique os parâmetros de caminho necessários. Os parâmetros de caminho necessários aparecem entre colchetes `{}` no caminho do ponto de extremidade. Substitua cada marcador de posição do parâmetro pelo valor desejado. Para obter mais informações, consulte [Caminho](#path).\n\n Por exemplo, o [ponto de extremidade \"Criar um problema\"](/pt/rest/issues/issues#create-an-issue) usa o caminho `/repos/{owner}/{repo}/issues` e os parâmetros de caminho são `{owner}` e `{repo}`. Para usar esse caminho em sua solicitação de API, substitua `{repo}` pelo nome do repositório no qual deseja criar um novo problema e substitua `{owner}` pelo nome da conta proprietária do repositório.\n\n### 3. Criar credenciais de autenticação\n\nCrie um token de acesso para autenticar sua solicitação. Você pode salvar seu token e usá-lo para várias solicitações. Atribua ao token todos os escopos ou permissões necessários para acessar o endpoint. Você enviará esse token em um cabeçalho `Authorization` com sua solicitação. Para obter mais informações, confira [Autenticação](#authentication).\n\n### 4. Fazer uma solicitação `curl`\n\nUse o comando `curl` para fazer sua solicitação. Para obter mais informações, consulte [a documentação do curl](https://curl.se/docs/manpage.html).\n\nEspecifique as seguintes opções e valores em sua solicitação:\n\n* **`--request` ou `-X`**, seguido pelo método HTTP como o valor. Para obter mais informações, consulte [método HTTP](#http-method).\n* **`--url`** seguido pelo caminho completo como o valor. O caminho completo é uma URL que inclui a URL base para a API REST GitHub (`https://api.github.com`) e o caminho do ponto de extremidade, assim: `https://api.github.com/PATH`. Substitua `PATH` pelo caminho do ponto de extremidade. Para obter mais informações, consulte [Caminho](#path).\n\n Para usar parâmetros de consulta, adicione `?` ao final do caminho e anexe o nome e o valor do parâmetro de consulta no formato `parameter_name=value`. Separe vários parâmetros de consulta com `&`. Se você precisar enviar uma matriz na cadeia de caracteres de consulta, use o parâmetro de consulta uma vez por item de matriz e acrescente `[]` após o nome do parâmetro de consulta. Por exemplo, para fornecer uma matriz de dois IDs de repositório, use `?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID`. Para saber mais, confira [Parâmetros de consulta](#query-parameters). Para obter um exemplo, confira [Exemplo de solicitação usando parâmetros de consulta](#example-request-using-query-parameters-1).\n* **`--header` ou `-H`:**\n * **`Accept`:** passe o tipo de mídia em um cabeçalho `Accept`. Para transmitir vários tipos de mídia em um cabeçalho `Accept`, separe os tipos de mídia com uma vírgula, por exemplo: `Accept: application/vnd.github+json,application/vnd.github.diff`. Para obter mais informações, confira [`Accept`](#accept) e [Tipos de mídia](#media-types).\n * **`X-GitHub-Api-Version`:** passe a versão da API em um cabeçalho `X-GitHub-Api-Version`. Para obter mais informações, consulte [`X-GitHub-Api-Version`](#x-github-api-version).\n * **`Authorization`:** Passe o token de autenticação em um cabeçalho `Authorization`. Observe que, na maioria dos casos, você pode usar `Authorization: Bearer` ou `Authorization: token` para transmitir um token. No entanto, se estiver passando um token Web JSON (JWT), você deverá usar `Authorization: Bearer`. Para obter mais informações, confira [Autenticação](#authentication). Para obter um exemplo de solicitação com um cabeçalho `Authorization`, confira [Exemplo de solicitação usando parâmetros de corpo](#example-request-using-body-parameters-1).\n* **`--data` ou `-d`** seguido por quaisquer parâmetros de corpo dentro de um objeto JSON. Se você não precisar especificar nenhum parâmetro de corpo em sua solicitação, omita essa opção. Para obter mais informações, confira [Parâmetros de corpo](#body-parameters). Para obter um exemplo, confira [Exemplo de solicitação usando parâmetros de corpo](#example-request-using-body-parameters-1).\n\n#### Solicitação de exemplo\n\nA solicitação de exemplo a seguir usa o [ponto de extremidade \"Obter Octocat\"](/pt/rest/meta/meta#get-octocat) para retornar o octocat como arte ASCII.\n\n```shell copy\ncurl --request GET \\\n--url \"https://api.github.com/octocat\" \\\n--header \"Accept: application/vnd.github+json\" \\\n--header \"X-GitHub-Api-Version: 2022-11-28\"\n```\n\n#### Exemplo de solicitação usando parâmetros de consulta\n\nO [endpoint \"Listar eventos públicos\"](/pt/rest/activity/events#list-public-events) retorna trinta questões por padrão. O exemplo a seguir usa o parâmetro de consulta `per_page` para retornar dois problemas em vez de 30 e o parâmetro de consulta `page` para efetuar fetch apenas na primeira página de resultados.\n\n```shell copy\ncurl --request GET \\\n--url \"https://api.github.com/events?per_page=2&page=1\" \\\n--header \"Accept: application/vnd.github+json\" \\\n--header \"X-GitHub-Api-Version: 2022-11-28\" \\\n https://api.github.com/events\n```\n\n#### Exemplo de solicitação usando parâmetros do corpo\n\nO exemplo a seguir usa o [ponto de extremidade —“Criar um problema”](/pt/rest/issues/issues#create-an-issue) para criar um novo problema no repositório the octocat/Spoon-Knife. Substitua `YOUR-TOKEN` pelo token de autenticação que você criou em uma etapa anterior.\n\n> \\[!NOTE]\n> Se você estiver usando um fine-grained personal access token, deverá substituir `octocat/Spoon-Knife` por um repositório que você possui ou que pertence a uma organização da qual você é membro. O token precisa ter acesso a esse repositório e possuir permissões de leitura e escrita para questões do repositório. Para saber mais, confira [Gerenciar seus tokens de acesso pessoal](/pt/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).\n\n```shell copy\ncurl \\\n--request POST \\\n--url \"https://api.github.com/repos/octocat/Spoon-Knife/issues\" \\\n--header \"Accept: application/vnd.github+json\" \\\n--header \"X-GitHub-Api-Version: 2022-11-28\" \\\n--header \"Authorization: Bearer YOUR-TOKEN\" \\\n--data '{\n \"title\": \"Created with the REST API\",\n \"body\": \"This is a test issue created by the REST API\"\n}'\n```\n\n
\n\n\n\nEsta seção demonstra como fazer uma solicitação GitHub à API REST usando JavaScript e [Octokit.js](https://github.com/octokit/octokit.js). Para ver um guia mais detalhado, confira [Script em API REST e JavaScript](/pt/rest/guides/scripting-with-the-rest-api-and-javascript).\n\n### 1. Instalação\n\nVocê deve instalar o `octokit` para usar a biblioteca Octokit.js apresentada nos exemplos a seguir.\n\n* Instale `octokit`. Por exemplo, `npm install octokit`. Para outras formas de instalar ou carregar `octokit`, consulte o [README do Octokit.js](https://github.com/octokit/octokit.js/#readme).\n\n### 2. Escolha um ponto de extremidade para sua solicitação\n\n1. Escolha um ponto de extremidade para o qual fazer uma solicitação. Você pode explorar a GitHub de [](/pt/rest) para descobrir endpoints que você pode usar para interagir com GitHub.\n\n2. Identifique o método HTTP e o caminho do ponto de extremidade. Você enviará tais informações com sua solicitação. Para obter mais informações, consulte [Método HTTP](#http-method) e [Caminho](#path).\n\n Por exemplo, o [ponto de extremidade \"Criar um problema\"](/pt/rest/issues/issues#create-an-issue) usa o método HTTP `POST` e o caminho `/repos/{owner}/{repo}/issues`.\n\n3. Identifique os parâmetros de caminho necessários. Os parâmetros de caminho necessários aparecem entre colchetes `{}` no caminho do ponto de extremidade. Substitua cada marcador de posição do parâmetro pelo valor desejado. Para obter mais informações, consulte [Caminho](#path).\n\n Por exemplo, o [ponto de extremidade \"Criar um problema\"](/pt/rest/issues/issues#create-an-issue) usa o caminho `/repos/{owner}/{repo}/issues` e os parâmetros de caminho são `{owner}` e `{repo}`. Para usar esse caminho em sua solicitação de API, substitua `{repo}` pelo nome do repositório no qual deseja criar um novo problema e substitua `{owner}` pelo nome da conta proprietária do repositório.\n\n### 3. Criar um token de acesso\n\nCrie um token de acesso para autenticar sua solicitação. Você pode salvar seu token e usá-lo para várias solicitações. Atribua ao token todos os escopos ou permissões necessários para acessar o endpoint. Você enviará esse token em um cabeçalho `Authorization` com sua solicitação. Para obter mais informações, confira [Autenticação](#authentication).\n\n### 4. Fazer uma solicitação com Octokit.js\n\n1. Importe `octokit` em seu script. Por exemplo, `import { Octokit } from \"octokit\";`. Para outras maneiras de importar `octokit`, confira o [README do Octokit.js](https://github.com/octokit/octokit.js/#readme).\n\n2. Crie uma instância de `Octokit` com o seu token. Substitua `YOUR-TOKEN` pelo seu token.\n\n ```javascript copy\n const octokit = new Octokit({ \n auth: 'YOUR-TOKEN'\n });\n ```\n\n3. Use `octokit.request` para executar sua solicitação.\n\n * Envie o método HTTP e o caminho como o primeiro argumento do método `request`. Para obter mais informações, consulte [Método HTTP](#http-method) e [Caminho](#path).\n * Especifique todos os parâmetros de caminho, consulta e corpo em um objeto como o segundo argumento do método `request`. Para obter mais informações, confira [Parâmetros](#parameters).\n\n Na solicitação de exemplo a seguir, o método HTTP é `POST`, o caminho é `/repos/{owner}/{repo}/issues`, os parâmetros de caminho são `owner: \"octocat\"` e `repo: \"Spoon-Knife\"`, e os parâmetros do corpo são `title: \"Created with the REST API\"` e `body: \"This is a test issue created by the REST API\"`.\n\n > \\[!NOTE]\n > Se você estiver usando um fine-grained personal access token, deverá substituir `octocat/Spoon-Knife` por um repositório que você possui ou que pertence a uma organização da qual você é membro. O token precisa ter acesso a esse repositório e possuir permissões de leitura e escrita para questões do repositório. Para saber mais, confira [Gerenciar seus tokens de acesso pessoal](/pt/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).\n\n ```javascript copy\n await octokit.request(\"POST /repos/{owner}/{repo}/issues\", {\n owner: \"octocat\",\n repo: \"Spoon-Knife\",\n title: \"Created with the REST API\",\n body: \"This is a test issue created by the REST API\",\n });\n ```\n\n O método `request` passa automaticamente o cabeçalho `Accept: application/vnd.github+json`. Para passar cabeçalhos adicionais ou um cabeçalho `Accept` diferente, adicione uma propriedade `headers` ao objeto que é passado como o segundo argumento. O valor da propriedade `headers` é um objeto em que os nomes dos cabeçalhos são as chaves e os valores dos cabeçalhos são os valores.\n\n Por exemplo, o código a seguir enviará um cabeçalho `content-type` com um valor de `text/plain` e um cabeçalho `X-GitHub-Api-Version` com um valor de `2026-03-10`.\n\n ```javascript copy\n await octokit.request(\"GET /octocat\", {\n headers: {\n \"content-type\": \"text/plain\",\n \"X-GitHub-Api-Version\": \"2026-03-10\",\n },\n });\n ```\n\n
\n\n## Como usar a resposta\n\nDepois 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.\n\n### Sobre o código de resposta e os cabeçalhos\n\nToda 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status).\n\nAlé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.\n\n\n\nPara exibir o código de status e os cabeçalhos, use a opção `--include` ou `--i` ao enviar sua solicitação.\n\nPor exemplo, essa solicitação obtém uma lista de problemas em especificado:\n\n```shell\ngh api \\\n--header 'Accept: application/vnd.github+json' \\\n--method GET /repos/octocat/Spoon-Knife/issues \\\n-F per_page=2 --include\n```\n\nE retorna um código de resposta e cabeçalhos semelhantes ao seguinte:\n\n```shell\nHTTP/2.0 200 OK\nAccess-Control-Allow-Origin: *\nAccess-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\nCache-Control: private, max-age=60, s-maxage=60\nContent-Security-Policy: default-src 'none'\nContent-Type: application/json; charset=utf-8\nDate: Thu, 04 Aug 2022 19:56:41 GMT\nEtag: W/\"a63dfbcfdb73621e9d2e89551edcf9856731ced534bd7f1e114a5da1f5f73418\"\nLink: ; rel=\"next\", ; rel=\"last\"\nReferrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin\nServer: GitHub.com\nStrict-Transport-Security: max-age=31536000; includeSubdomains; preload\nVary: Accept, Authorization, Cookie, Accept-Encoding, Accept, X-Requested-With\nX-Accepted-Oauth-Scopes: repo\nX-Content-Type-Options: nosniff\nX-Frame-Options: deny\nX-Github-Api-Version-Selected: 2022-08-09\nX-Github-Media-Type: github.v3; format=json\nX-Github-Request-Id: 1C73:26D4:E2E500:1EF78F4:62EC2479\nX-Oauth-Client-Id: 178c6fc778ccc68e1d6a\nX-Oauth-Scopes: gist, read:org, repo, workflow\nX-Ratelimit-Limit: 15000\nX-Ratelimit-Remaining: 14996\nX-Ratelimit-Reset: 1659645499\nX-Ratelimit-Resource: core\nX-Ratelimit-Used: 4\nX-Xss-Protection: 0\n```\n\nNeste exemplo, o código de resposta é `200`, o que indica uma solicitação bem-sucedida.\n\n
\n\n\n\nQuando você faz uma solicitação com Octokit.js, o método `request` retorna uma promessa. Se a solicitação tiver sido bem-sucedida, a promessa será resolvida para um objeto que inclui o código de status HTTP da resposta (`status`) e os cabeçalhos de resposta (`headers`). Se ocorrer um erro, a promessa será resolvida para um objeto que inclui o código de status HTTP da resposta (`status`) e os cabeçalhos de resposta (`response.headers`).\n\nVocê pode usar um bloco `try/catch` para capturar eventuais erros que ocorrerem. Por exemplo, se a solicitação no script a seguir for bem-sucedida, o script vai registrar o código de status e o valor do cabeçalho `x-ratelimit-remaining`. Se a solicitação não tiver sido bem-sucedida, o script vai registrar o código de status, o valor do cabeçalho `x-ratelimit-remaining` e a mensagem de erro.\n\nNo exemplo a seguir, substitua `REPO-OWNER` pelo nome da conta proprietária do repositório e `REPO-NAME` pelo nome do repositório.\n\n```javascript copy\ntry {\n const result = await octokit.request(\"GET /repos/{owner}/{repo}/issues\", {\n owner: \"REPO-OWNER\",\n repo: \"REPO-NAME\",\n per_page: 2,\n });\n\n console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers[\"x-ratelimit-remaining\"]}`)\n\n} catch (error) {\n console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers[\"x-ratelimit-remaining\"]}. Message: ${error.response.data.message}`)\n}\n```\n\n
\n\n\n\nPara exibir o código de status e os cabeçalhos, use a opção `--include` ou `--i` ao enviar sua solicitação.\n\nPor exemplo, essa solicitação obtém uma lista de problemas em especificado:\n\n```shell\ncurl --request GET \\\n--url \"https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2\" \\\n--header \"Accept: application/vnd.github+json\" \\\n--header \"Authorization: Bearer YOUR-TOKEN\" \\\n--include\n```\n\nE retorna um código de resposta e cabeçalhos semelhantes ao seguinte:\n\n```shell\nHTTP/2 200\nserver: GitHub.com\ndate: Thu, 04 Aug 2022 20:07:51 GMT\ncontent-type: application/json; charset=utf-8\ncache-control: public, max-age=60, s-maxage=60\nvary: Accept, Accept-Encoding, Accept, X-Requested-With\netag: W/\"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18\"\nx-github-media-type: github.v3; format=json\nlink: ; rel=\"next\", ; rel=\"last\"\naccess-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\naccess-control-allow-origin: *\nstrict-transport-security: max-age=31536000; includeSubdomains; preload\nx-frame-options: deny\nx-content-type-options: nosniff\nx-xss-protection: 0\nreferrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin\ncontent-security-policy: default-src 'none'\nx-ratelimit-limit: 15000\nx-ratelimit-remaining: 14996\nx-ratelimit-reset: 1659645535\nx-ratelimit-resource: core\nx-ratelimit-used: 4\naccept-ranges: bytes\ncontent-length: 4936\nx-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715\n```\n\nNeste exemplo, o código de resposta é `200`, o que indica uma solicitação bem-sucedida.\n\n
\n\n### Sobre o corpo da resposta\n\nMuitos 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`.\n\nAo 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.\n\n\n\nPor exemplo, você pode usar `>` a fim de redirecionar a resposta para um arquivo. No exemplo a seguir, substitua `REPO-OWNER` pelo nome da conta proprietária do repositório e `REPO-NAME` pelo nome do repositório.\n\n```shell copy\ngh api \\\n--header 'Accept: application/vnd.github+json' \\\n--method GET /repos/REPO-OWNER/REPO-NAME/issues \\\n-F per_page=2 > data.json\n```\n\nEm seguida, você pode usar o jq para obter o título e o ID do autor de cada issue:\n\n```shell copy\njq '.[] | {title: .title, authorID: .user.id}' data.json\n```\n\nOs dois comandos anteriores retornam algo como:\n\n```json\n{\n \"title\": \"Update index.html\",\n \"authorID\": 10701255\n}\n{\n \"title\": \"Edit index file\",\n \"authorID\": 53709285\n}\n```\n\nPara obter mais informações sobre o jq, confira [a documentação do jq](https://stedolan.github.io/jq/).\n\n
\n\n\n\nPor exemplo, você pode obter o título e a ID do autor de cada problema. No exemplo a seguir, substitua `REPO-OWNER` pelo nome da conta proprietária do repositório e `REPO-NAME` pelo nome do repositório.\n\n```javascript copy\ntry {\n const result = await octokit.request(\"GET /repos/{owner}/{repo}/issues\", {\n owner: \"REPO-OWNER\",\n repo: \"REPO-NAME\",\n per_page: 2,\n });\n\n const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})\n\n console.log(titleAndAuthor)\n\n} catch (error) {\n console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)\n}\n```\n\n
\n\n\n\nPor exemplo, você pode usar `>` a fim de redirecionar a resposta para um arquivo. No exemplo a seguir, substitua `REPO-OWNER` pelo nome da conta que possui o repositório e `REPO-NAME` pelo nome do repositório.\n\n```shell copy\ncurl --request GET \\\n--url \"https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2\" \\\n--header \"Accept: application/vnd.github+json\" \\\n--header \"Authorization: Bearer YOUR-TOKEN\" > data.json\n```\n\nEm seguida, você pode usar o jq para obter o título e o ID do autor de cada issue:\n\n```shell copy\njq '.[] | {title: .title, authorID: .user.id}' data.json\n```\n\nOs dois comandos anteriores retornam algo como:\n\n```json\n{\n \"title\": \"Update index.html\",\n \"authorID\": 10701255\n}\n{\n \"title\": \"Edit index file\",\n \"authorID\": 53709285\n}\n```\n\nPara obter mais informações sobre o jq, confira [a documentação do jq](https://stedolan.github.io/jq/).\n\n
\n\n#### Declarações detalhadas vs. resumidas\n\nUma 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.\n\n* 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.\n* 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 resumida do recurso.\n\nObserve que às vezes a autorização influencia a quantidade de detalhes incluídos em uma declaração.\n\nO motivo disso é porque alguns atributos são computacionalmente caros para a API fornecer, portanto GitHub , exclui esses atributos da representação resumida. Para obter esses atributos, você pode buscar a representação detalhada.\n\nA documentação fornece um exemplo de resposta para cada método da API. A resposta de exemplo ilustra todos os atributos que são retornados por esse método.\n\n#### Hipermídia\n\nTodos 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\nos 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](https://datatracker.ietf.org/doc/html/rfc6570) adequados.\n\nEm seguida, você pode expandir esses modelos usando algo como o gem [uri\\_template](https://github.com/hannesg/uri_template):\n\n```ruby\n>> tmpl = URITemplate.new('/notifications{?since,all,participating}')\n>> tmpl.expand\n=> \"/notifications\"\n\n>> tmpl.expand all: 1\n=> \"/notifications?all=1\"\n\n>> tmpl.expand all: 1, participating: 1\n=> \"/notifications?all=1&participating=1\"\n```\n\n## Limitação de taxa\n\nA GitHub API REST limita o número de solicitações que você pode fazer em um determinado período de tempo. Para obter mais informações sobre os limites de taxa e como verificar o status do limite de taxa atual, consulte [Limites de taxa para a API REST](/pt/rest/using-the-rest-api/rate-limits-for-the-rest-api).\n\n## Próximas etapas\n\nEste artigo demonstrou como listar e criar problemas em um repositório. Para obter mais prática, tente comentar numa questão, editar o título de uma questão ou fechar uma questão. Para obter mais informações, consulte o [ponto de extremidade \"Criar um comentário sobre o problema\"](/pt/rest/issues/comments#create-an-issue-comment) e o [ponto de extremidade \"Atualizar um problema\"](/pt/rest/issues/issues#update-an-issue).\n\nPara obter mais informações sobre outros pontos de extremidade que você pode usar, confira a [documentação de referência de REST](/pt/rest)."}