Introdução às APIs REST

Serviços de DevOps do Azure | Azure DevOps Server | Azure DevOps Server 2022

As APIs REST do Azure DevOps fornecem acesso programático poderoso a itens de trabalho, repositórios, compilações, versões e muito mais. Quer esteja a criar integrações personalizadas, a automatizar fluxos de trabalho ou a alargar as capacidades do Azure DevOps, compreender os padrões e conceitos fundamentais é essencial para uma implementação bem-sucedida.

Este artigo aborda os conceitos e padrões fundamentais para APIs REST do Azure DevOps. Para obter exemplos práticos de implementação, consulte Exemplos de API REST.

Estrutura do URL

As APIs seguem um padrão comum, conforme mostrado no exemplo a seguir:

VERB https://{instance}/{collection}/{team-project}/_apis/{area}/{resource}?api-version={version}

Serviços de DevOps do Azure

Para os Serviços de DevOps do Azure, instance é dev.azure.com/{organization} e collection é DefaultCollection, portanto, o padrão se parece com o exemplo a seguir:

VERB https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version={version}

Exemplo de endpoint:

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Azure DevOps Server

Para o Azure DevOps Server, instance é {server:port}. A porta padrão para uma conexão não-SSL é 8080.

A coleção padrão é DefaultCollection, mas você pode usar qualquer coleção.

Exemplos:

• SSL: https://{server}/DefaultCollection/_apis/projects?api-version=7.2
• Não-SSL: http://{server}:8080/DefaultCollection/_apis/projects?api-version=7.2

Autenticação

As APIs REST do Azure DevOps dão suporte a vários métodos de autenticação:

• Microsoft Entra ID - Recomendado para aplicativos de produção
• Personal Access Tokens (PATs) - Autenticação simples para scripts e testes
• OAuth 2.0 - Para aplicativos que não são da Microsoft
• Entidades de serviço - Para cenários de automatização

Formato da resposta

As APIs REST do Azure DevOps normalmente retornam respostas JSON. Aqui está um exemplo de estrutura de resposta:

{
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https://dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "TeamFoundationVersionControlprojects"
        }
    ],
    "count": 1
}

A resposta é JSON, que geralmente é o que você recebe de volta das APIs REST, embora haja algumas exceções, como blobs Git.

Métodos e operações HTTP

As APIs REST do Azure DevOps usam métodos HTTP padrão:

Solicitar cabeçalhos e conteúdo

Quando você fornecer um corpo de solicitação (geralmente com POST, PUT e PATCH), inclua cabeçalhos apropriados:

Content-Type: application/json

Para operações PATCH em itens de tarefas, use:

Content-Type: application/json-patch+json

Substituição do método HTTP

Alguns proxies da Web podem suportar apenas os verbos HTTP GET e POST, mas não verbos HTTP mais modernos, como PATCH e DELETE. Se suas chamadas podem passar por um desses proxies, você pode enviar o verbo real usando um método POST, com um cabeçalho para substituir o método. Por exemplo, talvez você queira atualizar um item de trabalho (PATCH _apis/wit/workitems/3), mas talvez seja necessário passar por um proxy que permita apenas GET ou POST. Você pode passar o verbo adequado (PATCH neste caso) como um parâmetro de cabeçalho de solicitação HTTP e usar POST como o método HTTP real.

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/wit/workitems/3

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Código de resposta

Compreender os códigos de resposta HTTP ajuda você a lidar com as respostas da API adequadamente:

Versionamento de API

As APIs REST do Azure DevOps são versionadas para garantir que os aplicativos continuem funcionando à medida que as APIs evoluem.

Orientações

• Sempre especifique a versão da API com cada solicitação (obrigatório)
• Formatar versões da API como: {major}.{minor} ou {major}.{minor}-{stage} (por exemplo, 7.2, 7.2-preview)
• Use revisões de visualização específicas quando disponíveis: 7.2-preview.1, 7.2-preview.2
• Atualize para versões lançadas quando as APIs de visualização forem preteridas

Utilização

Especifique a versão da API como um parâmetro de consulta de URL:

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2

Ou no cabeçalho da solicitação:

Accept: application/json;api-version=7.2

Para versões suportadas, consulte Controle de versão da API REST.

Mais recursos

Para obter orientações práticas de implementação e exemplos de código completos, consulte:

• Exemplos da API REST - Exemplos completos com a autenticação do Microsoft Entra ID
• Diretrizes de autenticação - Opções detalhadas de autenticação
• Controle de versão da API REST - Informações sobre o ciclo de vida da API
• OAuth 2.0 - Detalhes da implementação do OAuth

Próximos passos