API - Guia de Estilo

Nomenclatura padrão

818 views 19/03/2018 27/11/2018 admin 9

Nesta seção definimos uma nomenclatura padrão, sendo que uma grande parte dos sistemas utilizam operações padrão para suas funcionalidades de negócio, por exemplo, get, delete, etc.

Tópicos:

 

Idiomas utilizados nas APIs

As APIs devem ser escritas utilizando no idioma inglês (en-US), facilitando o entendimento pela comunidade internacional de desenvolvimento.
A documentação das APIs deve ser escrita no idioma português (pt-BR) visando facilitar sua criação pela equipe de desenvolvimento e adoção inicial por parceiros.

REST API

Na API de entidades é utilizado o estilo REST API, onde uma entidade é tratada como um recurso e os verbos HTTP a operação a ser realizada sobre ele. A seguir é listado as operações de CRUDL padrão na plataforma.

Exemplo

POST https://.../bridge/1.0/rest/ecossistema/reference_app/entities/task
{
...
}

Métodos

Verbo Responsabilidade Exemplo
GET Obtem uma coleção de itens de uma entidade (recurso) GET /task
GET Obtem uma entidade pela identificação única GET /task/{id}
POST Insere uma entidade informando todos os campos da entidade e entidades relacionadas. Nesta operação, é necessário informar todos os campos, inclusive das entidades relacionadas. POST /task
PATCH Insere uma entidade informando alguns campos da entidade e entidades relacionadas. Esta operação, é utilizada em inserções de entidades que referenciam uma outra entidade, mas não é necessário validar todos os campos da entidade referenciada, apenas a sua identificação única (id). PATCH /task
PUT Atualiza uma entidade informando todos os campos da entidade PUT /task/{id}
PATCH Atualiza uma entidade informando apenas alguns campos a serem atualizados e entidades relacionadas PATCH /task/{id}
DELETE Exclui uma entidade DELETE /task/{id}

 

RPC API – Métodos padrão

Os métodos padrão descrevem uma nomenclatura padronizada para as primitivas especificadas, permitindo que cada provedor escolha o idioma preferencial para suas APIs. Este estilo de API é utilizado nas Queries, Actions e Signals especificados na Service Definition Language (SDL).

Exemplo

POST https://.../bridge/1.0/rest/ecossistema/reference_app/queries/createTask
{
...
}

Métodos

get

  • Verbo HTTP: GET ou POST
  • Responsabilidade: Obter um item único
  • Cenário de uso: Em toda e qualquer consulta de dados em que resulte um único objeto, por exemplo, uma entidade, um valor único ou um objeto com várias propriedades.
  • Exemplos: getTask

list

  • Verbo HTTP: GET ou POST
  • Responsabilidade: Obter uma coleção de itens
  • Cenário de uso: Em toda e qualquer consulta de dados em que resulte uma coleção de objetos, por exemplo, uma lista de entidades, uma lista de objetos com várias propriedades, uma lista de itens filtradas. Normalmente utilizada em operações de consulta, pesquisa e filtragem de dados que resultem em 0 ou N objetos e de forma paginada.
  • Exemplos: listTasks

create

  • Verbo HTTP: POST
  • Responsabilidade: Criar um item
  • Cenário de uso: Utilizado para inserção de uma informação, principalmente em cenários onde a inserção de entidades via REST API não se aplicam.
  • Exemplos: createTasks

createBulk

  • Verbo HTTP: POST
  • Responsabilidade: Criar uma coleção de itens
  • Cenário de uso: Utilizado para inserção de várias informações em uma única chamada, principalmente em cenários de otimização e alto volume de dados.
  • Exemplos: createBulkTasks

export

  • Verbo HTTP: POST
  • Responsabilidade: >Exportar uma coleção de itens
  • Cenário de uso: Utilizado para exportação de dados em massa, normalmente para um leiaute de dados específico e de forma assíncrona, retornando um JobId para consulta posterior do status da exportação.
  • Exemplos: exportTasks

import

  • Verbo HTTP: POST
  • Responsabilidade: Importar uma coleção de itens
  • Cenário de uso: Utilizado para importação de dados em massa, normalmente a partir de um leiaute de dados específico e de forma assíncrona, retornando um JobId para consulta posterior do status da importação.
  • Exemplos: importTasks

retrieve

  • Verbo HTTP: GET ou POST
  • Responsabilidade: Obter um item único
  • Cenário de uso: Alternativa ao Get/Obter.
  • Exemplos: retrieveTask

update

  • Verbo HTTP: POST
  • Responsabilidade: Atualizar um item
  • Cenário de uso: Utilizado para atualizar uma informação, principalmente em cenários onde a atualização de entidades via REST API não se aplicam.
  • Exemplos: updateTask

updateMerge

  • Verbo HTTP: POST
  • Responsabilidade: Atualizar um item
  • Cenário de uso: Utilizado para atualizar apenas as propriedades informadas na requisição, por exemplo, atualizar apenas o campo Nome e E-Mail de uma entidade Colaborador.
  • Exemplo: updateMergeTask

 

ODATA API

Exemplo

POST https://.../bridge/1.0/odata/ecossistema/reference_app/task
{
...
}

Métodos

Verbo Responsabilidade Exemplo
GET Obtem uma coleção de itens de uma entidade (recurso) GET /task
GET Obtem uma entidade pela identificação única GET /task(id)
POST Insere uma entidade informando todos os campos da entidade e entidades relacionadas. Nesta operação, é necessário informar todos os campos, inclusive das entidades relacionadas. POST /task
PUT Atualiza uma entidade informando todos os campos da entidade PUT /task(id)
DELETE Exclui uma entidade DELETE /task(id)

Além disto, os seguintes parâmetros são suportados:

Nome Responsabilidade Exemplo
metadata Responsável por obter informações sobre a entidade GET /task/$metadata
top / skip Responsável por paginação dos dados GET /task?$top=10&$skip=10
count Responsável por obter a quantidade de itens na coleção GET /task/$count
orderby Responsável por ordenar os itens de uma coleção GET /task?$orderBy=name desc
filter Responsável por filtrar itens de uma coleção GET /task?$filter=name eq ‘ACME Inc.’

Mais informações sobre o OData pode ser consultado em sua página oficial.

 

Query Params padrão

Nome Responsabilidade Exemplo
offset / size Responsável por especificar a paginação de dados em uma coleção. Offset identifica a página de dados da coleção a ser obtida. Size identifica a quantidade de itens a ser obtido na página. Offset inicia em 0 e o size padrão é 10. Neste caso, para retornar do primeiro registro ao quinto, informa-se offset=0&size=5. Para obter do sexto registro ao décimo, informa-se offset=1&size=5. GET /task?offset=0&size=10
orderby Responsável por ordenar os itens de uma coleção. Onde é identificado o nome do campo, a ordenação e múltiplos campos separados por vírgula. GET /task?orderby=nome asc,idade desc
filter Responsável por filtrar itens de uma coleção GET /task?filter=something

 

Campos padrão

Nome Tipo Responsabilidade
createdBy String Nome do usuário que criou o recurso.
createdDate DateTime Data e hora UTC em que o recurso foi criado.
lastModifiedBy String Nome do usuário que alterou o recurso pela última vez.
lastModifiedDate DateTime Data e hora UTC em que o recurso foi alterado pela última vez.

 

Respostas padrão

Consulta de dados paginados

Quando houver a consulta de dados de forma paginada.

REQUEST:
/listFoo?offset=0&size=10
RESPONSE:
 {
   "totalPages" : 9,
   "totalElements" : 99,
   "contents" : [
     ...
   ]
 }

Em serviços que utilizam uma implementação de repositório com Spring Data, pode-se utilizar a classe PageRequest, informando o o offset e size, para obter um resultado paginado.

Exception

Quando houver a ocorrência de alguma situação não esperada, inválida ou não permitida.

Toda e qualquer mensagem de retorno da API deve considerar a internacionalização/localização, respeitando as preferências de idioma do usuário ou inquilino. Utilize o serviço Translation Hub da plataforma para gerenciar os artefatos traduzíveis.

HEADER:
HTTP Status Code com 4XX ou 5XX.
BODY:
{
  "errorCode" : 123,
  "message" : "My exception"
}

Na plataforma, os serviços que utilizam ServiceModel podem retornar códigos de erro específicos ao lançar uma ServiceException, informando a categoria, o código de erro e a mensagem de erro traduzida.

 

Códigos de retorno padrão

Quando houver a ocorrência de erro na execução de um serviço é importante que ele sinalize corretamente através de códigos.

Os códigos são padronizados no protocolo HTTP e diversas ferramentas e frameworks possuem automatismos para lidar com estes códigos padronizados. A seguir é listado os principais códigos utilizados na plataforma.

Na plataforma, os serviços que utilizam ServiceModel podem retornar códigos de erro específicos ao lançar uma ServiceException, informando o código de erro e a mensagem de erro.

 

throw new ServiceException(ErrorCategory.BAD_REQUEST, “Campo obrigatório”, originalException);

 

HTTP Code Título Descrição
200 OK Ação realizada com SUCESSO
400 BAD REQUEST Os dados enviados para o serviço estão inválidos ou incompletos, por exemplo, quando o JSON não é um conteúdo válido ou quando um campo obrigatório não foi informado.
401 UNAUTHORIZED O consumidor não está AUTENTICADO ou as credenciais informadas expiraram.
403 FORBIDDEN >O consumidor não está AUTORIZADO a utilizar este serviço. Por exemplo, não possui permissão a um determinado recurso.
404 NOT_FOUND Não encontrou o recurso solicitado, por exemplo, não encontrou uma entidade pelo ID informado.
409 CONFLICT O recurso que está tentando criar já existe ou ainda o recurso que está tentando atualizar já está diferente do estado original (eTag).
500 INTERNAL SERVER ERROR Quando ocorre uma Exception genérica ou não tratada. Normalmente não deveria ocorrer este tipo de código de erro.

Este artigo foi útil para você?