REST Framework
O REST Framework tem o objetivo de disponibilizar de forma simples os dados do sistema por meio de APIs HTTP que representam recursos, permitindo o acesso aos dados do sistema a partir de outras aplicações e interfaces web, desenvolvidos com outras tecnologias.
O termo recurso no contexto do Framework REST refere-se ao termo usado pela especificação do REST, e não à definição da classe de dados de Recursos (/Dados/Cadastrais/Recursos) usada no modelo de classes do ERP. O recurso é representado pela unidade de informação, ou seja, um dado referenciado por meio de uma URI, que pode ser consultado e/ou manipulado, geralmente associado a um registro do banco de dados. Também é usado o termo recurso para nos referenciarmos a uma coleção de elementos semelhantes, geralmente de uma mesma classe de dados.
O termo classe de dados no contexto de recurso REST refere-se a representação de modelo e visão de uma tabela em um banco de dados, ou ainda, definições das entidades do sistema.
Todas as entidades do sistema que devem ser visíveis pelas aplicações de terceiros devem ser mapeadas como recursos REST: Pedido, Cliente, etc. Esse mapeamento é feito por meio de objetos Javascript que os publicam, seguindo uma série de convenções definidas pelo REST Framework. Cada recurso REST que representa uma coleção de elementos é implementado por um único objeto Javascript, declarado num arquivo próprio armazenado na Virtual File System ou na Union File System. No contexto do REST Framework, usamos o termo controlador quando nos referimos a um desses objetos Javascript.
Os controladores são acessíveis às aplicações externas por meio de rotas HTTP configuradas pelo desenvolvedor. Uma rota HTTP mapeia uma URL e um verbo HTTP a um método do objeto controlador. A publicação de um recurso e suas ações nada mais é que a definição de um conjunto de rotas HTTP associadas a um controlador. Resumidamente, o REST Framework pode ser visto como:
- um formato de definições de rotas HTTP;
- objetos JavaScript controladores responsáveis por tratar as requisições das rotas configuradas e gerar respostas de acordo com o padrão REST; e
- APIs de manipulação de dados que facilitam a aplicação das regras de negócios nos controladores.
APIs HTTP padrão
A plataforma nginstack disponibiliza algumas APIs HTTP padrão para acesso e alteração de dados do sistema:
Outras APIs HTTP podem ser disponibilizadas pelos produtos desenvolvidos sobre a plataforma, como também podem ser criadas APIs customizadas pelos clientes finais da plataforma.
Restrições de uso
O REST Framework é uma funcionalidade experimental que ainda está em desenvolvimento, portanto podem ocorrer mudanças significativas na API. É recomendado que seja utilizado apenas com orientação do fornecedor do sistema.
Na versão atual, devem ser levadas em consideração as seguintes limitações:
- Apenas as classes de dados da plataforma foram revistas para utilizar o modelo de definição x-model, restringindo o uso das APIs HTTP padrão para as classes de dados da plataforma. Para fazer uso das APIs de ORM, é necessário revisar as definições de x-class para o novo modelo x-model/x-view.
- Ainda não existe uma API HTTP que permita a criação de tokens de autorização. Eles devem ser criados via a API AuthToken ou deve ser utilizada a autorização básica.