Ir para o conteúdo

Tutorial da API REST

O Harmony pode ser usado para consumir qualquer serviço web RESTful, também conhecido como API REST. Como as APIs REST são baseadas em HTTP, você se conecta a elas usando uma Fonte HTTP ou Destino HTTP no Harmony Design Studio. APIs REST não devem ser confundidas com serviços web que usam uma API SOAP, para os quais um Harmony método de serviço web é usado em seu lugar.

Este tutorial apresenta um exemplo completo de como consumir APIs REST no Harmony usando Atlassian Jira como um endpoint para fins de demonstração. O mesmo processo pode ser aplicado a qualquer endpoint que use uma API REST. Alguns outros exemplos de APIs REST incluem Magento, ServiceNow, Shopify, DocuSign, SharePoint, Epicor, Zendesk, Zoho e Sugar CRM, para citar alguns.

O público-alvo deste tutorial é alguém que não está familiarizado com APIs REST e seus testes e tem um conhecimento básico do Harmony. Se, em vez disso, você tiver mais experiência com um ou todos esses tópicos, recomendamos dar uma olhada no resumo das etapas abaixo para encontrar pontos de interesse. O último tópico, Usando uma API REST em operações, pode ser de maior interesse para aqueles com experiência em APIs REST, mas menos experientes com Harmony.

Esboço do Tutorial

Esses tópicos são abordados neste tutorial, apresentados na ordem em que devem ser concluídos:

  1. Pesquisando uma API REST
    Existem alguns itens específicos que você deve procurar na documentação de uma API e que serão necessários posteriormente para validar a API e fornecer na configuração no Design Studio. Isso inclui configurar o tipo de autenticação que você deseja que o Harmony use para autenticar com a API e obter URLs de solicitação, cabeçalhos de solicitação, estruturas de solicitação e estruturas de resposta esperadas.

  2. Validando uma API REST
    Antes de conectar-se a uma API REST com o Harmony, é altamente recomendável testar e validar usando uma ferramenta independente. Esta página orienta o teste de autenticação e a validação e salvamento de estruturas para cada solicitação e resposta.

  3. 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.

  4. 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:

    • Apenas uma estrutura de resposta
      Este padrão se aplica a métodos onde você precisa fornecer apenas uma estrutura de resposta e nenhuma estrutura de solicitação. Esse geralmente é o caso dos métodos GET, já que normalmente você apenas solicita que os dados sejam enviados de volta da API, em vez de fornecer dados à API. Você ainda está enviando uma solicitação à API, mas sua solicitação não está na forma de dados estruturados. A solicitação é feita simplesmente usando o URL da solicitação e quaisquer cabeçalhos de solicitação ou outras opções configuráveis definidas durante a configuração da origem HTTP.

    • Estruturas de solicitação e resposta
      Este padrão se aplica a métodos onde você fornece estruturas de solicitação e resposta. Esse é frequentemente o caso dos métodos POST, nos quais você solicita a criação de dados e depois recebe informações sobre o que foi criado. A resposta da API pode ser usada de qualquer forma, mas geralmente é o caso de usar os novos IDs de objeto em uma operação posterior.

    • Apenas uma estrutura de solicitação
      Este padrão se aplica a métodos onde você fornece uma estrutura de solicitação, mas não há dados estruturados retornados pela API REST. Para APIs que possuem apenas uma estrutura de solicitação, isso não significa que a API não responde; isso significa que a resposta da API pode ser tão simples quanto um código de status.

    • Nem uma solicitação nem uma resposta
      Este padrão se aplica a métodos que não aceitam dados de entrada estruturados nem retornam dados de saída estruturados. Nesses casos, a solicitação geralmente é especificada inteiramente com o URL e os cabeçalhos da solicitação; a resposta normalmente é um código de status.

Recursos Adicionais