Introdução às APIs REST

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

As APIs REST do Azure DevOps fornecem acesso programático avançado a itens de trabalho, repositórios, builds, versões e muito mais. Se você estiver criando integrações personalizadas, automatizando fluxos de trabalho ou estendendo recursos do Azure DevOps, entender os padrões e conceitos fundamentais é essencial para uma implementação bem-sucedida.

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

Estrutura de 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}

Azure DevOps Services

Para o Azure DevOps Services, instance é dev.azure.com/{organization} e collection é DefaultCollection, portanto, o padrão se parece com o seguinte exemplo:

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 Servidor de DevOps do Azure, 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:

• ID do Microsoft Entra – Recomendado para aplicativos de produção
• PATs (Tokens de Acesso Pessoal) – Autenticação simples para scripts e testes
• OAuth 2.0 – Para aplicativos que não são da Microsoft
• Principais de serviço – Para cenários automatizados

Formato da resposta

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

{
    "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ê obtém 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ê fornece um corpo da solicitação (geralmente com POST, PUT e PATCH), inclua os cabeçalhos apropriados:

Content-Type: application/json

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

Content-Type: application/json-patch+json

Substituição do método HTTP

Alguns proxies da Web podem dar suporte apenas aos verbos HTTP GET e POST, mas não verbos HTTP mais modernos, como PATCH e DELETE. Se suas chamadas puderem passar por um desses proxies, você poderá 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ódigos de resposta

Noções básicas sobre códigos de resposta HTTP ajuda você a lidar com as respostas da API adequadamente:

Controle de versão da API

As APIs REST do Azure DevOps têm versão para garantir que os aplicativos continuem funcionando à medida que as APIs evoluem.

Diretrizes

• Sempre especifique a versão da API com cada solicitação (necessária)
• Formatar versões de 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ível: 7.2-preview.1, 7.2-preview.2
• Atualizar para versões lançadas quando as APIs de visualização forem preteridas

Uso

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 com suporte, consulte o controle de versão da API REST.

Mais recursos

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

• Exemplos de API REST – Concluir exemplos com a autenticação da ID do Microsoft Entra
• 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
• Detalhes da implementação do OAuth 2.0 – OAuth

Próximas etapas