Tutorial da API REST
O Harmony pode ser usado para consumir qualquer serviço web RESTful, também conhecido como REST API. Como as REST APIs são baseadas em HTTP, você se conecta a elas usando uma fonte HTTP ou alvo HTTP no Jitterbit Design Studio. As APIs REST não devem ser confundidas com serviços da web que usam uma API SOAP, para a qual um Harmony método de serviço da web é usado em seu lugar.
Este tutorial aborda 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 REST API. Alguns outros exemplos de REST APIs 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 esteja familiarizado com APIs REST e seus testes, e que tenha conhecimento básico de Harmony. Se, em vez disso, você tiver mais experiência com um ou todos esses tópicos, recomendamos que você leia rapidamente o esboço das etapas abaixo para quaisquer pontos de interesse. O último tópico, Usando uma API REST em operações, pode ser de maior interesse para aqueles experientes com 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:
-
Pesquisando uma API REST
Existem alguns itens específicos que você deve procurar na documentação de uma API que você precisará 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. -
Validando uma API REST
Antes de conectar-se a uma API REST com Harmony, é altamente recomendável testar e validar usando uma ferramenta independente. Esta página aborda o teste de autenticação e a validação e salvamento de estruturas para cada solicitação e resposta. -
Conectando a uma API REST
No Design Studio, uma fonte ou alvo HTTP deve ser configurado para o método HTTP apropriado da sua solicitação (GET, PUT, POST, DELETE ou método personalizado) para que você possa usá-lo como 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 obedeça às mesmas restrições arquitetônicas, elas não são todas projetadas da mesma forma 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 em que você precisa fornecer apenas uma estrutura de resposta e nenhuma estrutura de solicitação. Este é geralmente o caso com métodos GET, já que você normalmente está apenas solicitando que dados sejam enviados de volta da API, em vez de fornecer dados para a API. Você ainda está enviando uma solicitação para a API, mas sua solicitação não está na forma de dados estruturados. A solicitação é feita simplesmente usando a URL da solicitação e quaisquer cabeçalhos de solicitação ou outras opções configuráveis definidas durante a configuração da fonte HTTP. -
Estruturas de solicitação e resposta
Este padrão se aplica a métodos onde você está fornecendo estruturas de solicitação e resposta. Este é frequentemente o caso com métodos POST, onde você está solicitando que dados sejam criados e então recebe de volta informações sobre o que foi criado. A resposta de volta da API pode ser usada de qualquer forma, mas é frequentemente 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 em que você fornece uma estrutura de solicitação, mas não há dados estruturados retornados pela REST API. Para APIs que têm apenas uma estrutura de solicitação, isso não significa que a API não responde; 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 nenhum dado de entrada estruturado nem retornam nenhum dado de saída estruturado. Nesses casos, a solicitação geralmente é especificada inteiramente com a URL e os cabeçalhos de solicitação; a resposta normalmente é um código de status.
-