SAP Gateway Zero-to-Hero — Pt. 6.4
SAP Gateway — Criando seu primeiro serviço: A importância de utilizar anotações
E aweeeee meu povo!!!!!
Quando criamos o nosso primeiro serviço passei rapidinho sobre um ponto que é muito importante, e fará a diferença sobre qual o seu nível como desenvolvedor. O que estou me referindo é a prática de utilizar anotações. Então antes de seguir a série para a parte onde passamos a não apenas a modelar mas agora implementar nossos serviços, vamos dar uma olhada rápida sobre a importância de utilizar anotações nos nossos serviços.
Anotações
O conceito de anotações em esquemas não é algo novo, e nasceu da necessidade de fornecer uma estrutura semântica do Conceptual Schema Definition Language (CSDL) para o Modelo de Dados de Entidade (EDM — Entity Data Model).
O CSDL é uma linguagem baseada em XML que pode ser usado para definir modelos conceituais baseados em EDM. Logo o EDM é um modelo de relacionamento de entidade (ER).
Tenho certeza que você já ouviu sobre este conceito de Entidade-Relacionamento, e ele está ai presente a muito e muitos anos diferindo do modelo relacional mais familiar, pois associações e entidades são conceitos de primeira classe.
O EDM define alguns tipos primitivos bem conhecidos, como Edm.String que utilizaremos em abundância, que são usados como blocos de construção para tipos estruturais, como tipos de entidades e tipos complexos, citados a alguns posts atrás.
Logo as entidades são instâncias de tipos de entidade (por exemplo, cliente, empregado ou nossa querida classe SFLIGHT) que são registros ricamente estruturados com uma chave.
A estrutura de um tipo de entidade é fornecida como vimos também em posts anteriores por suas propriedades, contendo por exemplo chaves que são formadas a partir de um subconjunto das propriedades do tipo de entidade.
A chave de entidade (por exemplo, como vimos previamente em alguns exemplos o CARRID) é um conceito fundamental que é usado para identificar e persistir entidades de entidades exclusivas e para permitir que instâncias de entidades participem de relacionamentos ou associações.
Temos esse tipo de especificação de maneira muito legal quando é utilizado SOAP, entretanto com a chegada do REST alguns desenvolvedores deixaram esse tipo de especificação de lado.
Mas com o OData a especificação do pouco que descrevi sobre uma entidade pode ser especificado de maneira muito simples, isso pois com as anotações podemos aplicar a construções de metadados.
Qualquer entidade que represente uma construção de EDM pode ser descrito em uma anotação.
Trocando em miúdos.
Anotações são lindas. Pois quando um desenvolvedor que não conhece tão bem o seu serviço precisar consumi-lo possivelmente a primeira coisa que ele fará será executar o $metadata para verificar a especificação dos campos disponíveis para serem consumidos:
No caso da imagem acima, estamos informando para o cliente que temos duas propriedades: CARRID e MostExpensive.
Além do seu tipo, informamos se elas são: Creatable, Updatable, Deletable, Sortable, Nullable e Filterable.
Essas opções são setadas no service builder quando estamos editando propriedades da entidade.
O significado das anotações é muito bem descrito na wiki da SAP, e pode ser visualizado no seguinte link:
Conclusão
Utilizar anotações serve para especificar uma informação, e por isso chamamos este recurso de metadata, assim quem consumir o nosso serviço será capaz de saber a especificação de cada campo, e esse é um dos pontos que torna o OData tão especial.
A utilização dessa prática ao desenvolver enriquece muito a sua API demonstrando um grau maior de maturidade. Fato é que se setarmos os campos com essas opções ou não, elas não refletirão diretamente no comportamento do nosso serviço, isso significa que caso você não marque um campo Updatable, ainda sim você será capaz de utiliza-lo para atualizar algo.
Então vamos prestar atenção a esse detalhe, pois novamente ressalto que ao escrever um serviço você tem a obrigação de deixar claro para quem irá consumir as propriedades de cada campo, pois só quem já consumiu um serviço sem qualquer especificação sabe como isso é cruel.
Até aqui venho descrevendo uma maneira de utilizar anotações de forma bastante automática, entretanto temos também como criar as nossas próprias anotações caso ocorra uma necessidade de algo mais específico. Isso é descrito no seguinte post:
E é isso ai, não deixe de conferir as referências abaixo, e se curtiu o post não deixe de participar comentando, compartilhando ou simplesmente segurando esse botão de aplausos para mostrar que é esse tipo de conteúdo que você deseja ter por aqui. Muito obrigado e até mais!
