Referência para as APIs REST

Visão Geral

Este documento deve esclarecer o uso da API REST do Engine e todos os conceitos relacionados a sua arquitetura. Ele tem o objetivo de tornar possível o consumo da API. Possíveis analogias com ações realizadas ao Web Framework poderão ser feitas para facilitar a compreensão.

Versão das APIs

Em cada API HTTP a versão será indicada na URL de acesso ao serviço.A URL das API HTTP seguem o padrão:

/api/<NOME_API>/v<VERSAO>/<RECURSO>

Por exemplo, a URL para acessar o esquema de uma classe de dados é /api/classes/v1/classes/-1898187810/schema. Pela URL, podemos afirmar que estamos acessando a API HTTP chamada Classes na sua versão 1.0.

Esquema

Neste ponto serão discriminadas as regras de consumo da API REST do Engine.

Representações de consumo

Toda requisição é composta pelo verbo HTTP, o caminho para manipulação de recurso, cabeçalho e corpo de requisição.

Os tipos de dado utilizados no corpo de uma requisição poderão apenas ser JSON ou Formulário codificado (x-www-form-encoded), contudo o uso de qualquer um desses tipos de dado depende da especificação da API RESTful para o ponto de acesso.

Este manual define como ponto de acesso a composição do verbo HTTP e caminho para manipulação de recurso.

Existem dois tipos de ponto de acesso para um recurso dentro da API são elas:

• • Rotas para manipulação de dados.

    • • Como o nome já diz a função dessas rotas é manipular os dados do sistema.

  • Rotas para exibir o esquema dos dados.

    • • Essas rotas servirão para discriminar os dados. Elas utilizam JSONSchema como resposta para definir os dados que precisam ser manipulados e os critérios abaixo se aplicam ao objetivo de uso do JSONSchema:

        • • Determinar quais são os possíveis valores de um campo.

          • Determinar quais valores de campos de uma chave estrangeira podem ser utilizados para referenciar a própria chave.

          • Determinar qual tipo de dado um campo possui.

          • Determinar quais são os campos requeridos.

Parâmetros e exemplos de consumo

Existem duas formas de realizar parametrização durante o consumo de um recurso, são elas:

• • Via querystring - Indicado somente para realização de filtragem dos dados.

curl -X GET -i http://localhost:8080/api/classes/v1/classes/-1898187810/entities?iclass=-1898187810&ikey=-1898186562 -u '<user>:<pass>'

• • Via corpo da requisição - Não deve ser utilizado quando o verbo HTTP for GET. A função indicada desta forma de parametrização é atualizar ou inserir dados no sistema.

curl -X POST -i http://localhost:8080/api/classes/v1/classes/-1898187810/entities -u '<user>:<pass>' -d '{ "iclass": -1898187810, "ishortcuts": [ 32145359 ], "ismtpusername": "web%group.com.br", "iemailaddress": "web@group.com.br", "ifullname": "Projetos", "iname": "Novo Grupo" }'

Algumas observações importantes sobre o corpo da requisição no formato JSON:

• • Um campo de múltiplos valores, que guarda mais de uma chave estrangeira (multiple lookup), deve ser tratado como array no caso em que houver múltiplos valores, se houver apenas um valor o campo pode ser definido com o próprio valor.

  • Um campo qualquer que guarda uma chave estrangeira (lookup) pode conter valores de outros campos do mesmo registro como nome, apelido ou identificador do produto, isso depende dos possíveis valores que podem ser servidos no serviço de esquema dos recursos.

Os exemplos de consumo deste material utilizam a ferramenta cURL

• • Exemplos de consumo não são fielmente executáveis, algumas partes precisam ser substituídas por informações especificas de cada usuário ou servidor tais como usuário e senha definidos em -u '<user>:<pass>' ou -i https://<domain>:<port>.

  • Os exemplos também são quebrados em linhas com o objetivo de facilitar a compreensão, para executá-los através de linha de comando certifique-se de que ele está sem quebra de linhas.

Representações de respostas

Os tipos de dado obtidos nas respostas poderão ser JSON ou HTML. Os campos em branco retornados em uma resposta terão o valor null e os campos lookups serão representados pelas chaves dos registros referenciados.

Datas

O formato de data esperado ou retornado pela API REST do Engine é YYYY-MM-DD. A API utiliza o formato timestamp ISO-8601 sem a informação de tempo preenchida devido ao fato do Engine não suportar. As datas no Engine possuem a informação referente ao tempo 00:00:00 e este horário sempre seria convertido com base no fuso horário do lugar ou região, se fosse realmente utilizado, por isso, não deve acontecer. Abaixo está um exemplo para esclarecer o propósito de não fornecer tempo em datas para a API REST do Engine.

• • Ex: Dada uma operação realizada no dia 19/03 em Brasília a qualquer hora, seria gravado como YYYY-03-19T00:00:00Z logo esta data convertida para o estado do Acre que possui fuso horário UTC-5 é 18/03 às 23:00, ou seja, o dia anterior.

Erros HTTP

Abaixo estão os possíveis erros e suas principais causas.

Verbos HTTP

Sempre que possível, os pontos de acesso tratam os seguintes verbos HTTP.

Autenticação

Existem duas formas de autenticar no sistema através da API REST do Engine. Requisições que requerem autenticação retornarão 401 Unauthorized quando o usuário não está autenticado. Caso o usuário esteja, mas não houver permissão, 403 Forbidden será retornado.

• • Basic Auth - Devem ser fornecidos o usuário e a senha através do cabeçalho HTTP de autorização no formato abaixo para garantir acesso ao sistema.

    • "Basic " + ('user:pass').encode('base64')

  • Access Token - Deve ser fornecido o token de autenticação através do cabeçalho HTTP de autorização no formato abaixo para garantir acesso ao sistema.

    • "Bearer " + token

APIs HTTP disponíveis