Informações da API
Este artigo tem a finalidade de oferecer uma introdução a API BackOffice da Microsys Sistemas, demonstrando seu funcionamento e definindo padrões de desenvolvimento. Este é o primeiro de um conjunto de artigos que foram elaborados para orientar desenvolvedores sobre o processo de integração.
Arquitetura da API
A API foi construída utilizando a arquitetura REST, e dispõe de endpoints que podem ser acessados através de métodos HTTP, esses endpoints produzem e consomem exclusivamente dados do tipo JSON, portanto toda requisição e resposta trabalhará com o formato application/json. Existem algumas exceções, estas estão devidamente evidenciadas nas respectivas documentações de cada método.
Endpoints da API
Os endpoints da API terão como padrão o context-path com o valor msysbackoffice/api que antecedem a URL.
Exemplo de um endpoid: http://localhost:9002/msysbackoffice/api/v1/recurso
Versionamento
A API terá versionamento dos endpoints que será controlado pela letra "v" que fará parte de cada endpoint mais o número da versão.
Exemplo: /api/v1/recurso
Requisições
A comunicação de qualquer serviço com a API se dá através de requisições HTTP em um determinado endpoint. A API trabalha com métodos GET, POST, PUT e DELETE, segue abaixo uma tabela representando a função de cada um desses métodos.
| Método | Descrição |
| GET | Utilizado para consultar recursos. Este é o único dos métodos citados que não gera alterações nos dados contidos na aplicação. |
| POST | Utilizado para criação de novos registros ou na chamada de métodos para processamento, como bloquear um usuário, por exemplo. |
|
PUT |
Utilizado para atualizar registros já existentes. |
|
DELETE |
Utilizado para remover registros já existentes. |
Retornos
Toda requisição efetuada à API é retornada para o cliente juntamente com um código de retorno, os códigos de retorno oferecidos pela API são os seguintes:
| Método | Descrição |
| 200 - OK | Indica que a requisição foi bem-sucedida. Toda requisição bem-sucedida sempre retornará esse código. |
| 400 - Bad Request | Indica que o servidor não pode ou não irá processar a requisição por ela conter algum problema, como estrutura do JSON inválida, por exemplo. |
|
401 - Unauthorized |
Indica que o cliente não possui credenciais de acesso válidas ou não está autenticado para acessar o recurso requerido. |
|
403 - Forbidden |
Indica que o cliente esta autenticado mas não possui autorização de acesso para acessar o recurso requerido. |
|
404 - Not Found |
Indica que a rota solicitada não existe e portanto o servidor não conseguiu encontrar o recurso solicitado. |
Além disso, algumas respostas retornarão dados em seu corpo, esses dados como mencionado anteriormente sempre serão do tipo application/json. As exceções serão sempre evidenciadas na documentação do respectivo método.
Autenticação no sistema
A API é protegida pela tecnologia de autenticação Basic Auth. Para possuir acesso e realizar operações no sistema o usuário precisa estar devidamente autenticado.
Para efetuar o login é necessário passar o usuário e senha no Authorization de cada requisição, caso contrário a API retornará o erro 401 - Unauthorized.
Segue um exemplo de requisição efetuada com sucesso:
Modularização da API
A API será criada em um projeto multi-módulo, onde um projeto principal irá utilizar outras bibliotecas (ou seja, um arquivo JAR que não é um aplicativo). A biblioteca irá expor seus endpoints que irão responder por um módulo ou fragmento do módulo (este quando poder ser compartilhado em mais módulos deve ser modularizado também).