Pesquise uma API REST

Introdução

Esta página destina-se àqueles que não estão familiarizados com o processo de coleta de informações em uma API específica e aborda os detalhes a serem procurados na documentação de uma API que são relevantes para configurar uma integração no Harmony.

Se você não estiver familiarizado com uma API específica, a primeira coisa a fazer é localizar sua documentação. Algumas APIs têm várias versões ou produtos, portanto, preste atenção à versão específica. Está se tornando mais comum que a documentação da API seja incorporada à implementação da API. Essas APIs podem ser documentadas usando a especificação OpenAPI/Swagger ou outras estruturas. Outra documentação de API que não está incorporada pode ser mais suscetível a imprecisões, tornando o teste e a validação ainda mais importantes.

Para fins deste tutorial, usamos Atlassian Jira Cloud REST API v2 como um exemplo.

Autenticação

Na documentação da API, procure instruções sobre como configurar o tipo de autenticação que você deseja que o Harmony use para autenticar com a API, como básica, OAuth ou baseada em token. Em seguida, configure a autenticação desejada conforme necessário.

Usando o exemplo do Jira, configuramos a autenticação básica seguindo a documentação do Jira em Autenticação básica para APIs REST. Com este tipo de autenticação, poderemos configurar o Harmony para usar um nome de usuário e senha para autenticar com Jira.

Mais adiante neste tutorial, mostraremos como você pode testar essa configuração (consulte Validating a REST API) e como usar o método de autenticação que você configurou para configurar uma origem ou destino HTTP no Design Studio (consulte Conectando-se a uma API REST).

Solicitar URL

Para cada chamada à API, você precisará saber o URL associado. A documentação deve mostrar como construir essa URL, que geralmente é uma combinação de uma URL base para o endpoint específico junto com parâmetros para a solicitação específica. A URL pode incluir parâmetros que devem ser substituídos pelos identificadores de registro específicos com os quais você deseja interagir.

Na documentação da API, o URL ou URL parcial pode ser listado para cada tipo de solicitação ou pode ser mostrado em uma solicitação completa. A documentação do Jira fornece ambos. Por exemplo, o caminho de URL parcial é fornecido para "Criar problema":

POST /rest/api/2/issue

A documentação do Jira também fornece exemplos para cada solicitação para uma variedade de ferramentas e linguagens (como cURL, Node.js, Java, Python e PHP). O URL completo completo com um nome de domínio fictício que precisará ser substituído pode ser encontrado em cada exemplo. A solicitação cURL de exemplo fornece o URL após o --url opção:

curl --request POST \
  --url 'https://<your-domain>.atlassian.net/rest/api/2/issue'

A documentação de uma API deve observar todos os parâmetros de consultar que podem ser adicionados ao final da URL. Posteriormente, no Design Studio, você poderá tornar dinâmicos o URL base e quaisquer parâmetros de consultar, substituindo-os por projeto ou variáveis globais no URL fornecido na configuração de origem ou destino HTTP. Um exemplo disso é fornecido posteriormente neste tutorial em Conectando-se a uma API REST.

Cabeçalhos de Solicitação

Para cada chamada para uma API REST, anote todos os cabeçalhos incluídos na solicitação.

No Design Studio, as informações de cabeçalho incluídas com mais frequência são especificadas durante a configuração padrão de uma origem ou destino HTTP, como autenticação e tipo de conteúdo. Observar os valores necessários ajuda a configurar corretamente a origem ou o destino. Cabeçalhos de solicitação adicionais podem ser especificados durante a configuração da origem/destino em Opções > Propriedades avançadas (e são abordados em Conectando-se a uma API REST).

No exemplo de solicitação cURL, as informações do cabeçalho são fornecidas como --header opções:

curl --request POST \
  --url 'https://<your-domain>.atlassian.net/rest/api/2/issue' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

Estruturas de Solicitação e Resposta

Para cada chamada para uma API REST, você precisará conhecer as estruturas de solicitação e resposta, se estiverem presentes.

Nem todas as chamadas de API têm uma estrutura de solicitação ou resposta. Se uma chamada usa uma (ou ambas) dessas estruturas depende da API específica. APIs bem documentadas geralmente fornecem a estrutura da solicitação. A estrutura da resposta pode ser fornecida, mas em qualquer caso pode ser obtida usando uma ferramenta como Postman ou SoapUI.

Para chamadas que aceitam dados de solicitação estruturada, a estrutura deve ser fornecida na documentação, contida na solicitação ou fornecida separadamente. As solicitações codificadas podem ser para uma variedade de ferramentas ou linguagens, com a payload em um formato esperado pela API, portanto, você precisa estar familiarizado com a ferramenta ou linguagem usada para saber onde procurar a estrutura da solicitação.

Por exemplo, na documentação da API do Jira para "Criar problema", a estrutura da solicitação está contida no --data opção para cURL (como visto abaixo) e é fornecido em vários outros idiomas. Pode ser necessário ajustar os dados de entrada para a solicitação específica, por exemplo, substituindo os valores de quaisquer campos (como a chave do projeto Jira e o tipo de pendência) por aqueles que são válidos para o endpoint específico. Você precisará fornecer essa estrutura de entrada ao validar a chamada em uma ferramenta como Postman, conforme abordado posteriormente em Validando uma API REST.

curl --request POST \
  --url 'https://<your-domain>.atlassian.net/rest/api/2/issue' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"fields": {"project": {"key": "TEST"}, "summary": "REST ye merry gentlemen.", "description": "Creating of an issue using project keys and issue type names using the REST API", "issuetype": {"name": "Bug"}}}'

Some API calls do not contain any structured input data for the request. For example, in the case of Jira's "Get Issue," the absence of --dados containing a structure indicates this call does not accept structured request data, as is common for GET calls.

curl --request GET \
  --url ' https:// <seu-domínio>.atlassian.net/rest/api/2/issue/<issueIdOrKey>' \
  -- cabeçalho 'Autorização: portador <access_token>' \
  -- cabeçalho 'Aceitar: application/json'

Using a GET can be helpful in cases where the API documentation may not have an accurate or complete request structure, or in cases where you have added custom fields. You can perform a GET on an existing object to obtain a list of possible fields or values, then use that structure later in Postman to test what might be accepted for the request in another method.

For calls that return structured response data from the API, if the documentation provides a sample response, note what format it is in and familiarize yourself with what is returned. Most REST APIs provide responses in JSON, but some APIs may provide XML or another type. For now, you don't need to copy the response provided by the documentation; we will generate the actual response from the API later for use in Design Studio (see Validating a REST API).

Take note of any documented status codes that are expected to be returned. These will be useful as reference to interpret the response received from the API after making the request. For example, the following table shows codes that can be returned from the Jira "Create Issue" request. In addition to a status code, error messages with helpful information may be returned in a structured response.

Jira "Get Issue" Status Codes

Outras Informações Exclusivas do Endpoint

A importância geral de se familiarizar com seu endpoint não pode ser enfatizada o suficiente. A documentação de uma API pode fornecer recomendações ou cuidados para ajudá-lo ao longo do caminho. Por exemplo, na documentação do Jira, há notas especiais sobre permissões, expansão de recursos, paginação e cabeçalhos especiais. Estar ciente do que está disponível (ou indisponível) ajudará você a projetar integrações bem-sucedidas e a enfrentar quaisquer desafios que encontrar.

Próximos Passos

Depois de configurar a autenticação desejada e se familiarizar com a documentação da API, consulte estas páginas para as próximas etapas:

• Validando uma API REST
  Antes de se conectar a uma API REST com Harmony, é altamente recomendável testar e validar usando uma ferramenta independente. Esta página mostra como testar a autenticação e validar e salvar estruturas para cada solicitação e resposta.

• Conectando-se a uma API REST
  No Design Studio, uma fonte ou destino HTTP deve ser configurado para o método HTTP apropriado de sua solicitação (GET, PUT, POST, DELETE ou método personalizado) para que você possa usá-lo em uma operação. Embora esta página se concentre em opções de configuração comuns, as páginas Fonte HTTP e Alvo HTTP fornecem informações mais detalhadas sobre todas as opções disponíveis para configuração.

• Usando uma API REST em Operações
  Embora cada API REST siga as mesmas restrições de arquitetura, nem todas são projetadas da mesma maneira para cada método HTTP. Como cada solicitação e resposta específica depende da API específica, apresentamos quatro padrões de design para projetar operações.