Modelagem da API



As nossas APIs possuem diversos recursos, dessa forma vale descrevermos um pouco cada um deles antes de você analisar a documentação dos nossos Endpoints.

Tecnologias e Padrões

REST

É um estilo de arquitetura que define um conjunto de restrições e propriedades baseados em HTTP.

Web Services que obedecem ao estilo arquitetural REST, ou Web Services RESTful, fornecem interoperabilidade entre sistemas. Mais informações.

JSON

É um formato leve de troca de informações/dados entre sistemas, amplamente utilizado. Mais informações.

UTF-8

Define um padrão de caracteres de comunicação entre sistemas distribuídos. Mais informações.

ISO-8601

Padrão utilizado para envio e retorno de campos do tipo data/hora. Esse padrão utiliza a Time Zone.

"Padrão": "YYYY-MM-DDThh:mm:ss.sTZD"
"Exemplo": "2019-01-22T13:37:00.000-03:00" 

Mais informações.

Métodos HTTP

Nossas APIs seguem o padrão RestFul e utilizam o verbo HTTP referente a cada operação.

Ação Método Descrição
Create POST Cria um novo recurso.
Read GET Consulta um recurso ou uma lista.
Update PUT Atualiza um recurso existente.
Delete DELETE Remove um recurso existente. Essa operação não pode ser desfeita.

Códigos de Sucesso

Código HTTP Descrição Métodos HTTP
200 Indica que o processamento foi realizado com sucesso. GET
201 Indica que o recurso foi criado com sucesso. POST
202 Indica que o processamento será assíncrono, portanto, irá retornar um link “process” onde será possível verificar o status. POST
204 Indica que o recurso foi atualizado com sucesso. PUT

Códigos de Erro no Cliente

Código HTTP Descrição
400 Erro na requisição, Json mal formatado ou campos inválidos.
401 Erro na autenticação do usuário.
403 Usuário sem acesso ao recurso.
404 Recurso não encontrado.
405 Método não permitido.
409 Recurso já existente.
412 Exceções de negócio.

Códigos de Erro no Servidor

Código HTTP Descrição
5xx Erro interno inesperado do servidor.

Resposta Padrão de Erros

{ 
  "type":"Business_Logic_Error", "description":"Business logic error.",
  "notifications":[ "Erro 1'", "Erro x'" ]           
}

Paginação

No momento da listagem de um recurso deve-se utilizar os parâmetros de paginação page e size.

Veja um exemplo de requisição:

GET https://zuul.monkey.exchange/v2/sponsors/123/payables?page=0&size=20

Caso não seja informado nenhum valor o padrão será 0 para o parâmetro page e 20 para o parâmetro size.

Ordenação

As APIs de listagem contam com ordenação e ela é feita através do parâmetro sort, Você pode utilizar mais de uma ordenação na mesma requisição.

Veja um exemplo de requisição:

GET https://zuul.monkey.exchange/v2/sponsors/123/payables?page=0&size=20&sort=updatedAt,desc&sort=status,asc

Filtros

As APIs de listagem possuem um mecanismo de filtro e isso é feito através do parâmetro search e você pode combinar as buscas utilizam AND ou OR.

Veja um exemplo de requisição:

GET https://zuul.monkey.exchange/v2/sponsors/123/payables?search=supplierGovernmentId:24212752000184 AND supplierName:*Fornecedor* AND paymentDate>2020-04-23 AND (externalId:123 OR invoiceNumber:123)

Utilize os campos retornados no json para montar seu filtro, Veja as alternativas de busca:

: - Para busca por equalidade. Ex: supplierName:Fornecedor.

> - Para busca onde o atributo deve ser maior ou igual ao valor informado. Ex: paymentValue>200

< - Para busca onde o atributo deve ser menor ou igual ao valor informado. Ex: paymentValue<200

* - Para busca onde o atributo pode começar com (supplierName:Forne*), terminar com (supplierName:*cedor) ou conter (supplierName:*orne*).

Hypermedia (HATEOAS)

HATEOAS (Hypermedia as the Engine of Application State) possibilita que as aplicações que se integram com a API possam interagir através de links.

Dessa forma, ao acessar um recurso você irá, através de links, saber quais outros recursos se relacionam com ele e quais ações podem ser executadas.

A utilização de HATEOAS permite que a disponibilização de novas interações ocorra de forma dinâmica e que as aplicações consumidoras tomem conhecimento das novas opções de interação sem que sejam impactadas.

Veja um exemplo de links:

"_links":{
   "self":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123/signatures/0zkvnbfZsE",
      "type":"GET"
   },
   "documents":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123/signatures/0zkvnbfZsE/documents{?type}",
      "type":"GET",
      "templated":true
   },
   "approve":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123/signatures/0zkvnbfZsE/approve",
      "type":"POST"
   },
   "unapprove":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123/signatures/0zkvnbfZsE/unapprove",
      "type":"POST"
   },
   "buyer":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123",
      "type":"GET"
   },
   "purchase":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123/purchases/0zkvnbfZsE",
      "type":"GET"
   }
}

Veja um exemplo de paginação:

"_links":{
   "first":{
      "href":"http://zuul.monkey.exchange/v2/buyers/123/signatures?status=UNAPPROVED&page=0&size=20"
   },
   "self":{
      "href":"http://zuul.monkey.exchange/v2/buyers/123/signatures?status=UNAPPROVED&page=0&size=20"
   },
   "next":{
      "href":"http://zuul.monkey.exchange/v2/buyers/123/signatures?status=UNAPPROVED&page=1&size=20"
   },
   "last":{
      "href":"http://zuul.monkey.exchange/v2/buyers/123/signatures?status=UNAPPROVED&page=12&size=20"
   }
},
"page":{
   "size":20,
   "totalElements":249,
   "totalPages":13,
   "number":0
}