Cloud Jasmin DesenvolvimentoConceitos
DesenvolvimentoConceitos
Conceitos
Voltar | Lista de artigos

Características da Web API Primavera

Última alteração a 30/08/2022

O que é uma API?

O termo API significa “Application Programming Interface” e refere-se tradicionalmente a uma “camada da aplicação” que expõe a sua lógica de negócio de uma forma uniformizada, permitindo que seja utilizada por aplicações externas que pretendam interagir com essa aplicação.

No contexto de uma aplicação Web, este termo é sinónimo de uma camada de Web services que as aplicações cliente podem utilizar para obter e/ou atualizar dados da respetiva aplicação. Esses serviços podem assumir diferentes nomes, formas e formatos, mas a tendência atual é permitir o acesso a estas funcionalidades através de API REST.

Mais informações sobre as boas práticas de utilização e conceitos em https://restfulapi.net/

O que é uma API REST?

REST significa “Representational State Transfer” e é um padrão de design utilizado para criar uma API que utilize o protocolo HTTP como meio de comunicação.

O artigo que descreve este “modelo” pode ser consultado em http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm.

O protocolo HTTP é uma excelente plataforma para a disponibilização de uma API porque já é utilizado atualmente por todos os dispositivos com ligação à Internet.

Na sua essência o HTTP é um sistema de pedido/resposta (request/response). O cliente (a aplicação externa) envia um pedido para um determinado endpoint e esse endpoint (a API) responde.

Há vários aspetos do protocolo HTTP importantes no contexto de uma Web API:

  • Resources – o REST utiliza recursos (resources) com um endereço para definir a estrutura da API. São os URL que devem ser utilizados para aceder às entidades e operações disponibilizadas pela API.
  • Request Verbs – descrevem o que se pretende fazer com o resource. Existem vários verbs disponíveis: GET, POST, PUT, DELETE. Mais informação: https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html.
  • Request Headers – são instruções adicionais enviadas no pedido. Por exemplo, detalhes de autorização ou o tipo de resposta pretendido. Mais informação: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html.
  • Request Body – os dados enviados no pedido. Por exemplo, num POST (para criar um novo registo) os dados são enviados no body como JSON ou XML.
  • Response Body – representa os dados da resposta devolvida pelo servidor, também em JSON ou XML.
  • Response Status Code – o código da resposta que indica ao cliente o estado do pedido. Mais informação: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

Numa API REST, os resources são normalmente as entidades disponibilizadas pela aplicação (cliente, artigo, fornecedor, encomenda, etc.).

O verbo enviado no pedido indica à API que operação se pretende realizar sobre a entidade. Por exemplo, um GET indica que se pretende obter os dados de uma entidade. Um POST significa que se pretende criar uma nova entidade.

Existem convenções comuns implícitas nas API REST que facilitam a sua utilização de uma forma uniforme entre todas as entidades.

Eis alguns exemplos de possíveis endereços e pedidos de uma API:

ResourceVerbResultadoStatus Code
/productsGETA lista de produtos200 (OK)
/products?colour=redGETA lista de produtos que têm a cor vermelha200 (OK)
/productsPOSTCriação de um produto201 (Created)
/products/81GETOs dados do produto com o id 81200 (OK)
/products/81PUTAtualização do produto com o id 81204 (No Content)
/products/81DELETERemoção do produto com o id 81204 (No Content)

Web API PRIMAVERA

A Web API permite aceder a todas as entidades do sistema, permitindo a realização de todas as operações sobre essas entidades (criação, atualização, remoção, consulta e listagem).

Para que se possa utilizar a Web API é necessário que se verifiquem as seguintes condições:

  • Os pedidos devem ser efetuados no contexto de um utilizador, por isso, primeiro é necessário criar uma conta de utilizador e uma subscrição.
  • A aplicação externa deve ser registada no sistema para ter acesso ao token de segurança que permite identificar os pedidos realizados pela aplicação externa.
  • Os pedidos à Web API devem ser configurados de acordo com as instruções do protocolo OAuth e do sistema de autenticação.

Endpoints

A Web API Jasmin disponibiliza os endpoints de serviço num formato de rotas específico.

URL base:

https://baseurl/api/{account}/{subscription}/{module}/{resource}/

A rota tem sempre a mesma estrutura e usa os seguintes elementos variáveis:

  • {account}: identifica a conta do cliente que será utilizada no pedido.
  • {subscription}: identifica a subscrição do cliente que será utilizada no pedido. Note que um cliente pode ter várias subscrições.
  • {module}: identifica o módulo a que pertence o resource do pedido. Os resources estão categorizados em módulos que agrupam resources sobre os mesmos temas (sales, purchases, taxes, etc.).
  • {resource}: identifica o resource que será utilizado no pedido.

Exemplo:

https://baseurl/api/9999/9999-9999/sales/invoice/

Em cada um dos endpoints estão disponíveis as operações (verbs) GET, POST ou DELETE.

Mais informação: Quais são os endpoints da Web API?

Exemplos de Endpoints

Como é natural numa Web API REST, o URL e os parâmetros do pedido dependem da operação a realizar. Eis alguns exemplos concretos para a entidade (resource) de encomenda de vendas:

  • Para obter a lista de todas as encomendas de venda (com o verb GET):
    https://baseurl/api/{tenant}/{subscription}/sales/orders
    
  • Para obter uma página da lista de todas as encomendas de venda (com o verb GET):
    https://baseurl/api/{tenant}/{subscription}/sales/orders?page=1&pageSize=25
    
  • Para criar uma nova encomenda (com o verb POST):
    https://baseurl/api/{tenant}/{subscription}/sales/orders
    
  • Para obter uma determinada encomenda usando o respetivo id (com o verb GET):
    https://baseurl/api/{tenant}/{subscription}/sales/orders/53c4ee41-bd16-41f9-a348-3b24cbb4d8c8
    
  • Para obter uma determinada encomenda usando a sua chave (com o verb GET):
    https://baseurl/api/{tenant}/{subscription}/sales/orders/ECL/2017/12
    
  • Para anular uma determinada encomenda (com o verb DELETE):
    https://baseurl/api/{tenant}/{subscription}/sales/orders/ECL/2017/12
    

Parâmetros de Entrada

Como referido acima, os endpoints da Web API requerem a identificação da conta e da subscrição do cliente para todos os pedidos.

Para além disso, será necessário fornecer no pedido outros parâmetros, dependendo do endpoint e da operação pretendida.

Em alguns casos, esses parâmetros deverão ser especificados nos headers do pedido (como a informação de autenticação). Noutros, devem ser especificados no URL do endpoint (como o identificador da entidade a obter num GET ou o número e tamanho da página ao consultar a lista de uma entidade).

Existem ainda casos em que os dados devem ser fornecidos em formato JSON no corpo da mensagem, como na criação de uma entidade.

A documentação de referência da Web API especifica exatamente os parâmetros do pedido para cada um dos casos.

Resultados

Os resultados devolvidos em cada pedido dependem do tipo de pedido e da entidade em causa.

Em determinados pedidos, como a anulação de uma entidade, o resultado será apenas um status code. Na generalidade dos casos, o sistema devolve um status code e os dados do resultado no corpo da mensagem. Por exemplo, o resultado da consulta de uma entidade pela sua chave será a entidade toda formatada em JSON.

Mais informação: Formato dos pedidos e respostas

Autenticação

A Web API requer que todos os pedidos efetuados sejam autenticados. O método de autenticação utilizado é o standard OAuth 2.0.

Adicionar aos favoritos ou partilhar este artigo
Esta página foi útil?
Obrigado pelo seu voto.

login para deixar a sua opinião.

Obrigado pelo seu feedback. Iremos analisá-lo para continuarmos a melhorar!
Artigos Relacionados
Quais são os endpoints da Web API? Formato dos pedidos e respostas Mensagens de erro Entidades base e extensões Características dos recursos da Web API