01. Recursos

O termo recurso apresentado neste manual 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 Sistema Bematech 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 Bematech ERP que são visíveis pelas aplicações de terceiros são mapeadas como recursos REST: Pedido, Cliente, etc. Este mapeamento é feito por meio de objetos Javascript que os publicam, seguindo uma série de convenções definidas pelo framework de web services RESTful do Engine, denominado apenas por REST Framework. Cada recurso REST que representa uma coleção de elementos é implementado por um único objeto Javascript, declarado num arquivo próprio armazenado no Virtual File System ou no Union File System. Neste documento, usamos o termo controlador quando nos referimos a um desses objetos Javascript.

Os controladores implementados no ERP seguem o seguinte padrão de localização na árvore de classes:

<raiz da licença do produto>/controllers/<nome do controlador>.js

• • A classe raiz deverá chamar-se "controllers", filha direta da classe raiz do produto (Ex: /products/Store/controllers).

  • No diretório controllers, deverão ser criados todos os controladores definidos por esse produto do Bematech ERP.

Observe que este caminho é apenas convencionado, não havendo no Framework REST nenhum mecanismo que force essa estrutura. Essa flexibilidade permite a declaração de controladores na UnionFS, que possui uma organização de diretórios diferente.

Para que um controlador seja carregado, é necessário que ele seja utilizada por uma ou mais definições de rota. As definições das rotas são declaradas em arquivos no diretório Configurações/Rotas HTTP.

Nas seções posteriores desta documentação, serão abordados novamente, com maior profundidade, o controle de versionamento dos recursos, as definições de rotas e os controladores.

Nomes concretos x abstratos

Alcançar um alto nível de abstração é um objetivo frequente de arquitetos de API’s. Entretanto, uma grande abstração muitas vezes não é significativa para os desenvolvedores. Geralmente, classes e recursos abstratos tornam um sistema mais extensível, coeso e simples de manter, em detrimento da intuitividade da API para os desenvolvedores. Uma API que modela tudo no mais alto nível de abstração prejudica a capacidade do desenvolvedor de intuir quais funcionalidades o recurso possui. Por exemplo, os comportamentos esperados de um recurso Cliente são mais claros para um desenvolvedor dos que os de um recurso Entidade. Por outro lado, o mesmo recurso Entidade poderá ser utilizado para manipular todas as entidades do sistema, como Fornecedores, Locais de Escrituração, Funcionários, etc.

A estratégia adotada pelo Bematech ERP na criação de suas primeiras APIs é a de criar uma API RESTful o mais similar possível as APIs já existentes nos objetos de gestão, da forma mais abstrata possível. O objetivo é que seja liberado rapidamente o acesso a todas as capacidades do modelo de dados do ERP, mesmo que não seja da forma mais simples para os consumidores da API. Após essa primeira etapa, serão construídas APIs mais especializadas e concretas para os casos em que haja benefício real de clareza ou desempenho.

Seguindo essa estratégia, o Framework disponibiliza todo o cadastro genérico por meio de uma API REST abstrata. Os desenvolvedores dos módulos do sistema Bematech ERP devem utilizar preferencialmente essa API, em vez de criar recursos especializados para os dados cadastrais. O foco deverá ser disponibilizar os dados de movimentações, acessados por meio dos objetos de gestão.

Nomes de classes e métodos em Português

No Bematech ERP, classes e métodos seguem um padrão de nomenclatura, onde os nomes devem ser escritos em português, ao contrário do Web Framework, onde os nomes são em inglês. Nos objetos controladores do sistema não haveria de ser diferente, os nomes são apenas em Português, reduzindo o esforço cognitivo do desenvolvedor, dispensando-o de se preocupar com a língua que deve usar ao nomear um método.

< Introdução Página Anterior | Proxima página Versionamento >