Validar uma API REST¶

Introdução¶

Nesta página, mostramos como usar uma ferramenta independente para validar as estruturas de solicitação e resposta de uma API REST. Esta página continua o Tutorial da API REST usando API REST do Atlassian Jira Cloud v2 como exemplo, continuando a partir da etapa anterior de Pesquisando uma API REST. Este passo a passo destina-se a usuários inexperientes que não estão familiarizados com testes e validação de API.

Antes de conectar-se a uma API REST com Harmony, é altamente recomendável testar e validar usando uma ferramenta independente por vários motivos:

• Solução de problemas focada: A maioria dos problemas com APIs REST no Harmony são o resultado de não ter construído a solicitação conforme necessário para recuperar a resposta desejada da API. A execução dessa solução de problemas usando uma ferramenta independente garante que as solicitações específicas sejam válidas antes da introdução da automação.

• Iteração rápida: Ao projetar uma integração, talvez você não conheça todos os campos ou valores desejados ou não consiga fazer solicitações válidas na primeira tentativa. A realização de testes rápidos que geram feedback imediato pode ajudá-lo a criar solicitações para seu caso de uso específico de maneira eficiente, permitindo modificar sua solicitação até que a resposta desejada seja gerada.

• Estruturas reais: A documentação da API para amostras de estruturas de solicitação e resposta pode estar desatualizada, não levar em consideração uma configuração específica para seu endpoint, estar incompleta ou ser imprecisa de alguma outra maneira. Com base na experiência, recomendamos fortemente o uso das respostas de dados estruturados reais da própria API para que o Harmony saiba como processar seus dados corretamente.

Há diversas ferramentas disponíveis para validação de APIs REST. Neste tutorial, usamos o Postman devido à sua simplicidade, mas você pode usar qualquer ferramenta de sua preferência, como SoapUI. Se disponível, você também pode usar o portal do desenvolvedor de um provedor de API ou a funcionalidade de teste OpenAPI/Swagger, desde que as estruturas de solicitação e resposta sejam fornecidas.

Autenticação de Teste¶

A primeira etapa do teste é garantir que você possa se conectar com êxito à API REST usando o tipo de autenticação configurado.

Na documentação da API, encontre um URL de solicitação para testar que forneça uma resposta. Usar um GET para testar a autenticação geralmente é a maneira mais simples de garantir que você possa se conectar. Outros métodos em que os dados são transferidos para o endpoint podem exigir permissões que você poderá diagnosticar e resolver problemas posteriormente, depois de saber que a peça de autenticação está funcionando.

Primeiro, construa o URL da solicitação, substituindo o URL base pelo do seu endpoint específico, conforme aplicável. Por enquanto, não se preocupe em fornecer os detalhes específicos da solicitação; só queremos ter certeza de que podemos estabelecer uma conexão. Usando "Get Create Issue Metadata" do Jira como exemplo, encontramos na documentação que o URL da solicitação é construído usando https://<your-domain>.atlassian.net/rest/api/2/issue/createmeta. No Postman, como o método é GET, usamos o menu suspenso para selecionar GET e inserir o URL de solicitação para nosso endpoint.

Em seguida, forneça os detalhes de autenticação do seu endpoint. No Postman, isso é feito na seção Autorização. Como estamos usando autenticação básica, selecionamos Autenticação básica e inserimos as credenciais do Jira que usaremos no Design Studio posteriormente. Embora este exemplo use autenticação básica, você pode usar qualquer tipo de autenticação compatível com seu endpoint.

Com o URL da solicitação e as informações de autenticação inseridas, envie a solicitação à API (no Postman, clique em Enviar). Se a conexão for bem-sucedida, você deverá receber uma resposta da API, geralmente como uma estrutura, um código de status de sucesso ou ambos, dependendo do método e da API específicos. Se a conexão falhar, verifique a documentação da API e seu endpoint em busca de erros de configuração.

Valide e Salve Estruturas para Cada Solicitação e Resposta¶

Depois de confirmar que você pode se conectar à API REST com sucesso, use o mesmo processo para (1) validar cada solicitação que você deseja que o Harmony possa fazer para a API interagir com os dados do seu endpoint e (2) salvar as estruturas de solicitação e resposta (se presentes) para separar arquivos que você precisará posteriormente no Design Studio.

Para validar cada solicitação no Postman, siga as mesmas etapas anteriores para fornecer o URL da solicitação (para cada chamada) e os detalhes de autenticação.

Se uma chamada exigir uma estrutura de solicitação, da qual você deveria ter obtido uma amostra anteriormente na documentação da API, será necessário fornecê-la no Postman. Na seção Body, selecione o botão de opção raw e use o menu suspenso para definir o formato apropriado (content-type). No exemplo, como acontece com a maioria das APIs REST, o formato é JSON (application/json). Cole a estrutura da solicitação e faça os ajustes necessários para que a solicitação seja válida (por exemplo, alterando a chave do projeto Jira e o tipo de problema). Esses ajustes dependerão da sua solicitação de API real.

Depois de preencher as informações da solicitação, clique em Enviar. Se necessário, diagnosticar e resolver problemas e itere até obter a estrutura de resposta da API desejada. Os dados reais incluídos no exemplo de resposta não são relevantes, pois a API REST fornecerá os dados reais ao Harmony no momento em que a solicitação for feita.

Depois de ter a estrutura de dados para usar em sua integração, salve cada estrutura de solicitação e resposta (se presente) em seus próprios arquivos. Certifique-se de salvar no formato de arquivo correto; a maioria das APIs REST fornecem respostas em JSON, mas algumas podem usar XML ou outro tipo, dependendo da API. Salve os arquivos onde você puder acessá-los ao configurar seu projeto no Design Studio.

Observe que se você não pretende usar todos os campos fornecidos na resposta em sua integração, isso é perfeitamente normal e esperado. Você pode simplesmente deixá-los ou, se desejar, pode optar por removê-los manualmente da estrutura da amostra. Mas você deve certificar-se de que todos os campos que planeja usar estejam incluídos; caso contrário, você não poderá usá-los no Harmony.

Neste exemplo, usamos o Postman para validar as estruturas de solicitação e resposta a seguir e, em seguida, salvamos essas estruturas em arquivos locais. Estes são os arquivos que precisaremos fornecer posteriormente no Design Studio durante a configuração da transformação para que o Harmony possa processar os dados corretamente.

Jira GET "obter Problema"¶

Neste cenário comum, primeiro usamos um método GET que retorna campos e valores reais de um objeto existente no endpoint. Depois de ver quais são esses campos e valores, poderíamos usá-los posteriormente em um PUT, POST, DELETE ou outro método.

• Solicitar URL: OBTER https://my-domain.atlassian.net/rest/api/2/issue/TEST-10

• Estrutura da solicitação: Nenhuma. A documentação da API Jira indica que nenhum dado de entrada está associado à solicitação, o que faz sentido porque o objeto específico solicitado é fornecido no URL da solicitação.

• Estrutura de resposta: Editamos a estrutura de resposta para remover campos que não queremos usar (uma etapa opcional) e salvamos em um arquivo local chamado Jira_GET_GetIssue_Response.json:

  Jira_GET_GetIssue_Response.json

  {
      "expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
      "id": "10572",
      "self": "https://my-domain.atlassian.net/rest/api/2/issue/10572",
      "key": "TEST-10",
      "fields": {
          "issuetype": {
              "self": "https://my-domain.atlassian.net/rest/api/2/issuetype/10003",
              "id": "10003",
              "description": "A task that needs to be done.",
              "name": "Task",
              "subtask": false
          },
          "project": {
              "id": "10200",
              "key": "TEST"
          },
          "priority": {
              "self": "https://my-domain.atlassian.net/rest/api/2/priority/3",
              "iconUrl": "https://my-domain.atlassian.net/images/icons/priorities/medium.svg",
              "name": "Medium",
              "id": "3"
          },
          "labels": [],
          "versions": [],
          "status": {
              "name": "To Do"
          },
          "description": "This task is for manually updating JIRA because there is no integration in place.",
          "security": null,
          "summary": "Manual Updates",
          "comment": {
              "comments": [],
              "maxResults": 0,
              "total": 0,
              "startAt": 0
          }
      }
  }
  

Jira POST "criar Problema"¶

Agora enviamos uma solicitação para criar um novo objeto usando alguns dos mesmos campos retornados do GET. Para saber os valores possíveis, você poderia primeiro chamar um GET diferente que retorne a mesma estrutura.

• URL de solicitação: POSTAGEM https://my-domain.atlassian.net/rest/api/2/issue/

• Estrutura da solicitação: Salva em um arquivo local chamado Jira_POST_CreateIssue_Request.json.

  Jira_POST_CreateIssue_Request.json

  {
      "fields": {
         "project":
         {
            "key": "TEST"
         },
         "summary": "Jitterbit REST API Integration",
         "description": "Build an integration in Jitterbit so we can automatically sync our systems using our endpoint's REST API.",
         "priority": {
          "name": "Medium"
          },
         "issuetype": {
            "name": "Task"
         }
     }
  }
  

• Estrutura de resposta: Salva em um arquivo local chamado Jira_POST_CreateIssue_Response.json. Também podemos verificar nosso endpoint para ver se o novo problema foi criado ou fazer um GET no identificador do novo objeto.

  Jira_POST_CreateIssue_Response.json

  {
      "id": "10576",
      "key": "TEST-11",
      "self": "https://jitterbitse.atlassian.net/rest/api/2/issue/10576"
  }
  

Jira PUT "editar Problema"¶

A seguir, editamos o problema que acabamos de criar para modificar os valores de alguns de seus campos existentes e adicionar novos.

• Solicitar URL: COLOCAR https://my-domain.atlassian.net/rest/api/2/issue/TEST-11

• Estrutura da solicitação: Salva em um arquivo local chamado Jira_PUT_EditIssue_Request.json.

  Jira_PUT_EditIssue_Request.json

  {
    "update": {
      "comment": [
        {
          "add": {
            "body": "Ticket updated via REST API."
          }
        }
      ]
    },
    "fields": {
      "priority": {
          "name": "Highest"
      },
      "labels": ["business-priority", "customer-priority"]
      }
  }
  

• Estrutura de resposta: Nenhuma. No Postman, recebemos um código de status 204, que a documentação da API indica ser a resposta esperada se o problema for atualizado com sucesso. Também podemos verificar nosso endpoint no aplicativo web Jira ou realizar outro GET para ver se as atualizações foram feitas.

Jira DELETE "excluir Problema"¶

Por fim, excluímos o objeto que criamos e editamos.

• URL de solicitação: EXCLUIR https://my-domain.atlassian.net/rest/api/2/issue/TEST-11

• Estrutura da solicitação: Nenhuma. O identificador do objeto é fornecido na URL.

• Estrutura de resposta: Nenhuma. O código de status retornado é 204, que na documentação da API do Jira indica que o problema foi removido com sucesso. Isso também pode ser verificado no aplicativo Web Jira ou confirmado com um GET malsucedido.

Próximos Passos¶

Depois de validar e salvar a estrutura de cada solicitação e resposta, consulte estas páginas para ver as próximas etapas:

• Conectando-se a uma API REST
  No Design Studio, uma origem 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 nas opções de configuração comuns, as páginas Fonte HTTP e Destino 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.