Tutorial de Modelagem de APIs REST

Aprenda de uma forma iterativa a modelar uma API REST do zero.

Imagem

©Felipe Firmo
Todos os Direitos Reservados
São Paulo – Brasil – 2019
 Apresentação
Bom dia, boa tarde, boa noite! Seja muito bem vindo ao Tutorial de Modelagem de APIs REST!
Meu nome é Felipe Firmo e serei seu guia nessa jornada.

Parabéns por estar aqui! Só o fato de você ter comprado o livro, ou até mesmo ter 'dado uma
olhada' demonstra que você se preocupa com algo que poucos profissionais de TI se preocupam,
com a modelagem!

A idéia desse livro é ser um guia inicial para profissionais com pouca ou nenhuma experiência
em integração se sentirem mais confortáveis com modelagem de serviços, tendo assim mais
embasamento e tranquilidade para fazer suas atividades. Para isso, teremos que passar
rapidamente por muitos conceitos mas, para não ficar um livro massante, vou me reter ao
essencial. Em alguns casos mais importantes, vou dar uma pequena explicação, em outros vou
encaminhar para um post ou até mesmo indicar algum livro,

MAS o mais importante é não deixar essa sopa de letrinhas te desanimar. Continue,
mesmo que não compreenda completamente o tópico, você sempre poderá voltar mais
tarde, ou até mesmo me enviar um e-mail com dúvidas pelo livro@[Link].

Como este livro está organizado

O livro está estruturado em duas partes, Fundamentos e REST eles foram estruturados para Commented [FGF1]: Verificar partes
serem lidos em seqüência, principalmente se você ainda não tem experiência em modelagem
ou em REST.

Avisos

Antes de iniciar o conteúdo propriamente dito, preciso alertar uma das coisas mais
importantes que aprendi na faculdade:

"Não julgue alguém por um código, você não sabe a situação, hora, nem condições em
que ele foi escrito"

Dito isso, vou precisar me apoiar em alguns cenários, mas sempre com o objetivo de usa-lo
como cenário para ilustrar o que eu entendo como mais correto, e nunca para julgar quem fez
algo similar.

Acho que as primeiras coisas que devo falar sobre modelagem são:
 Não existe certo nem errado em modelagem. Existem sistemas bem modelados e
sistemas mal modelados;
 Uma modelagem nunca estará pronta, sempre que um novo profissional analisar a
modelagem, ele pode trazer novos pontos de vista;
SUMÁRIO
Aviso Legal................................................................................................................................ 2
Apresentação ........................................................................................................................... 3
Como este livro está organizado .......................................................................................... 3
Avisos ................................................................................................................................... 3
Conceitos .................................................................................................................................. 5
Modelagem ...................................................................................................................... 5
API .................................................................................................................................... 5
REST .................................................................................................................................. 5
Modelagem de entidades ........................................................................................................ 6
Resumindo ........................................................................................................................... 8
Modelagem de APIs ................................................................................................................. 9
Serviços ................................................................................................................................ 9
Inicando a modelagem do nosso serviço ............................................................................. 9
Procedures, Métodos, Operações ou Capacidades?! ........................................................ 10
Continuando a modelagem ................................................................................................ 11
Resumindo ......................................................................................................................... 11
Nomenclatura ........................................................................................................................ 12
Contato de Serviço Padronizado ........................................................................................ 12
Visibilidade do Serviço ....................................................................................................... 12
Convenção de Nomenclatura............................................................................................. 12
 Conceitos
Agora sim, podemos começar ... logo no título temos 3 termos que merecem menção:
 Modelagem;
 API;
 REST;

Modelagem
Ok, como explicar modelagem de uma forma simples, e rápida? Pesquisando sobre o assunto,
ela tem origem em alguns ‘papas’ do desenvolvimento de software, mas que só ouvi falar na
faculdade ... então .... fora do escopo deste livro. Como uma das principais características de um
bom analista de sistemas/desenvolvedor é a preguiça, fui na WIKIPEDIA, e não é que a definição
estava boa?!

Modelagem de software é a atividade de construir modelos que

expliquem as características ou o comportamento de um software ou de um
sistema de software. Na construção do software os modelos podem ser
usados na identificação das características e funcionalidades que o
software deverá prover (análise de requisitos), e no planejamento de sua
construção. Commented [FGF2]: [1] Introdução à Modelagem de
Software por Flávio de Oliveira Silva (2015)

Antes que esse tema se estenda demais, o foco principal do livro é modelagem, para isso (mais uma referência:
precisamos dar um passo atrás e, a partir de alguns requisitos, vamos fazer uma modelagem de [Link]
com-uml/20140)
dados antes de iniciar a modelagem do serviços e APIs. Ou seja, vamos criar um modelo, uma
representação do que se irá construir. Acredito que quando inciarmos ficará mais claro.

API
API é um acrônimo de Application Programming Interface ou Interface de Programação de
Aplicação. Quando comecei a desenvolver, o uso mais comum desse termo era para se
referenciar bibliotecas (nativas ou de terceiros) da própria plataforma de desenvolvimento
(java, .net, etc). Muito complicado né, com um exemplo fica mais simples:

— Agora complicou, como você vai exportar esses dados no formato excel?
— Isso é fácil, achei uma API que faz isso, só passar os parâmetros e nome do arquivo!

Mas com o passar do tempo, esse termo se popularizou se referenciando a serviços REST
expostos na internet. Como as APIs do Twitter, Facebook, etc. Hoje em dia, a maioria dos
sistemas expõem APIs para tudo, pois sua própria interface gráfica (tela) as utiliza.

REST
Agora a coisa está ficando mais técnica, não sei se você reparou, mas tive que utilizar o termo
REST no exemplo anterior. REST também é um acrônimo, de Representational State Transfer ou
Transferência Representacional de Estado. Ok, eu sei que isso não faz o menor sentido a primeira
vista (nem a segunda, terceira, rs) mas para nosso escopo não precisamos nos preocupar com
isso. O importante é saber que REST é um estilo arquitetural baseado no protocolo HTTP para
criação de serviços. Basicamente ele define algumas regras e restrições para criarmos nossos
serviços e APIs.

Agora já podemos iniciar propriamente o conteúdo \o/

 Modelagem de entidades
Antes de iniciar com a modelagem, precisamos conhecer os requisitos. E esta é a segunda
vez que o apareceu um termo novo: Requisito é uma necessidade, uma capacidade ou
caracterísctica que o sistema precisa ter.

Vamos imaginar que trabalhamos em uma loja que deseja criar um e-commerce. Isso poderia
ser um requisito épico (muito grande), que deve ser quebrado em vários outros requisitos para
viabilizar sua construção. Um requisito menor seria:

Como um cliente logado eu devo ser capaz de criar um novo pedido, contendo o
endereço de entrega, data e uma lista de ítens para fazer uma compra.

Através desse requisito, podemos identificar uma entidade, o Pedido. Também conseguimos
identificar alguns atributos do Pedido, como endereço de entrega, data e itens. Não está
explicito neste requisito, mas este pedido precisa poder ser recuperado no futuro, então ele
precisará ser armazenado em um banco de dados. Commented [FGF3]: Mantenho este trecho?

Até este ponto temos informações suficientes para esboçar o primeiro diagrama, um ‘papel
de pão’ onde rabiscamos esta informação para que fique mais facil compreender o que precisa
ser feito. Além disso, com essa imagem fica mais facil de entender e explicar o que precisa ser
feito para outros desenvolvedores. Isto é modelar em outras palavras:

Provavelmente mesmo sem nenhum conhecimento na área você conseguiria chegar neste
diagrama, concorda? Por este motivo não vou me aprofundar neste tema, pois apenas isto já é
suficiente para ir para a ‘próxima fase’ que seria o refinamento deste esboço.

Uma evolução natural seria poder suportar pedidos com vários itens, não somente três. Para
isso, vamos trocar os ultimos três elementos por uma lista de pedidos:
 Dando um pouco mais de atenção para os itens, eles precisariam de um código, nome, link
e quantidade e valor. Não tem nenhum problema com o termo código, mas normalmente neste
cenário, o termo sku é usado:

Vamos preencher esta entidade para visualizar melhor:

 Mas ainda assim não está muito bom, pois dá margem para vários problemas:
 Qual cidade e estado? O que é Conjunto 35? E Terceiro Andar?
o Como conhecemos o domínio, conseguimos inferir algumas coisas, mas e se
fosse um sistema médico, ou químico?
 Qual o dia da data? Pode facilmente ser 7, 8 ou 10. O mesmo vale para mês e ano.

Resumindo

Nas ultimas páginas já inicamos a modelagem da nossa primeira entidade. Muito dificil? Não
consegue enxergar os próximos passos?

Calma, esse sentimento é normal. A principal dificuldade de ensinar e aprender modelagem,

é: Não existe uma modelagem 100% certa ou errada, não existe uma fórmula exata. Como Commented [FGF4]: Citação?
costumo dizer:

Modelagem é um assunto indigesto, ele vai levar um tempo até você compreender e digerir
todas as informações.

Isso acontece pois modelar é uma forma de pensar no sistema, como ‘projetar’ o sistema.
Por este motivo vou deixar você com estas indagações, e muitas outras que enventualmente
estão te perturbando. É natural este sentimento e sugiro que reflita bastante sobre cada detalhe
da modelagem até agora, deixei vários problemas não resolvidos. Mas fique tranquilo, mais
tarde voltamos nestes pontos.

Agora que já está de cabeça quente, vamos mudar um pouco o foco, quando voltarmos nesse
assunto acredito que fique mais fácil.
 Modelagem de APIs
Antes de começarmos a falar de APIs, você reparou que o termo serviço aparece várias vezes
no capítulo anterior? Então vamos ‘voltar para o mundo real’ para entender melhor o que é um
Serviço e como ele se relaciona com APIs.

Serviços Commented [FGF5]: É necessário uma definição mais

No mundo real, quando precisamos de um serviço, seguimos os seguinte procedimento: formal de serviço?
1. Vamos a uma ‘loja’;
2. Entendemos a forma de contratação;
3. Decidimos se realmente vamos contrata-lo;
4. Fornecemos alguma informações/coisas;
5. Aguardamos o prazo;
6. Pagamos e recebemos o resultado de serviço.

Vamos detalhar um pouco melhor, e para isso usar outro exemplo: Uma Lavanderia:

Eu como cliente gostaria que minhas roupas fossem lavadas e passadas.

Acima está nosso novo requisito (ficou mais claro este o que é um requisito?). Agora vamos
aos passos descritos acima:
1. Vamos a uma ‘loja’: Ok, neste caso vamos à lavanderia;
2. Entendemos a forma de contratação: Neste caso é ‘pós-pago’, ou seja, pagamos na
retirada;
3. Decidimos se realmente vamos contrata-lo: Caso concorde com o valor, prazo, etc,
decido contratar este serviço;
4. Fornecemos alguma informações/coisas: Neste caso, precisamos deixar as roupas. É
preciso também decidir qual serviços vou querer: Tipo Lavagem, vou incluir o serviço de
passagem das roupas? Lavagem express? Entrega?
a. Com isso receberemos o prazo e valor;
5. Aguardamos o prazo;
6. Pagamos e recebemos o resultado de serviço: Aqui efetuamos o pagamento e
recebemos as roupas;

Simples? Um pouco extenso, mas fazemos isso diariamente com diversos outros serviços:
mercado; disk pizza; etc. Cada um tem sua particularidade, mas todos eles tem uma forma de
contrato ou seja, esperam receber algumas informações, tem um prazo e um resultado.

Inicando a modelagem do nosso serviço

Agora vamos tentar trazer esse exemplo para nosso cenário anterior. O requisito do capítulo
passado era:

Eu como um cliente logado eu devo ser capáz de criar um novo pedido, contendo o
endereço de entrega, data e uma lista de ítens para fazer uma compra.

Aqui já temos algumas informações do que o Serviço faz e o que espera receber. Na nossa
analogia anterior, vamos pular alguns itens e ir direto para os passos de 4 à 6:
4. Fornecemos alguma informações/coisas: Neste caso, seriam as informações do
requisto:
 a. Endereço de entrega
b. Data
c. Lista de ítens
5. Aguardamos o prazo: Em TI os serviços, costumam retornar entre 100ms e 1s no
máximo; Esse prazo é chamado de SLA: Service Level Agreement;
6. Pagamos e recebemos o resultado de serviço: Um resultado deste serviço pode ser:
a. Código do pedido
b. Status atual;
Usando termos mais técnicos podemos resumir que um Contrato de Serviço envolve seus
parâmetros de entrada (item 4), SLA (item 5) e parâmetros de saída (item 6);

Podemos também entender que um Serviço executa algo a partir de seus parâmetros de
entrada e deve retornar seus parâmetros de saída dentro de seu SLA.

Ficou claro a diferença entre Contrato de Serviço e o Serviço propriamente dito?

Pois bem, podemos dizer que chamamos o Contrato de Serviço de API, simples assim! Então
posso ter uma API (Contrato => Parâmetros e SLA) que executa um Serviço e retorna o resultado
ao consumidor.

<<imagem consumidor -> lavanderia (ou atendente?) -> serviço de lavagem de roupas>>

--

E acaba de surgir outro termo, consumidor. Para o nosso contexto, consumidor é um outro
software que irá acessar, chamar ou consumir nossa API. Hoje em dia os consumidores mais
comuns são websites e aplicativos móveis, mas nada impede de um sistema chamar o outro
através de uma API.

<<imagem consumidor -> API -> serviço>>

Então para o escopo deste livro, sempre que eu falar API, trata-se do Contrato, da Interface. O
Serviço está fora do escopo do livro. Commented [FGF6]: Verificar melhor local para esta frase

Procedures, Métodos, Operações ou Capacidades?!

A partir daqui vou aprofundar mais, mas não muito, na parte técnica. Vou começar a usar
mais termos do dia-a-dia do desenvolvimento de sistemas.

Não sei como teve contato com desenvolvimento, mas eu começei com linguagens
procedurais (Pascal e Basic). Nestas linguagens um programa é dividido em Procedures que
executam uma função, possuem parâmetros de entrada e um parâmetro de saída.

Depois entrei em linguagens Orientadas a Objetos, onde cada Classe possi Métodos. Mas
para o escopo deste livro, essa mudança foi basicamente de nomenclatura.

Mais tarde, quando começei a trabalhar com Serviços, o termo mais usado era Operações,
mas na prática, pouca coisa mudava em relação aos primos mais velhos (Método e Procedure).
Finalmente ao ler mais sobre o assunto, nos livros do Thomas Erl, Papa da Arquitetura
Orientada a Serviços, o termo mais usado era Capacidade.
 Por enquanto, vamos usar o termo mais usado para Serviços, que é Operação! No próximo
capítulo, vai mudar novamente rs.

Continuando a modelagem
Relembrando nosso requisito:

Eu como um cliente logado eu devo ser capaz de criar um novo pedido, contendo o
endereço de entrega, data e uma lista de ítens para fazer uma compra.

Já identificamos uma entidade Pedido no capítulo anterior. As entidades sempre serão

substantivos, já as operações ..... verbos! Neste requisito qual o verbo mais importante? Criar,
certo? Então essa é a operção descrita neste requisito. Então temos o Serviço Pedido com a
operação Criar. O diagrama do nosso Serviço ficaria assim:

<<imagem>>
Pedido
Criar

Resumindo
Neste capítulo, começamos a explorar a modelagem de serviços, compeendemos o que é um
Contrato de Serviço, que é composto (inicialmente) pelos parâmetros de entrada, SLA e
parâmetros de saída.
Vimos também que os serviços possuem operações e como identificar o serviço e a operação a
partir de um requisito.
 Nomenclatura
Como já sobrevoamos as modelagens de Entidade e API, vem uma das partes mais filosóficas
da arte da modelagem, o batismo. Muitos desenvolvedores afirmam que dar nomes
significativos é uma das partes mais desafiadoras do processo de desenvolvimento.
No desenvolvimento tradicional (código) as classes, métodos e variáveis tem que ser bem
nomeadas para promover a ‘manutenibilidade’, ou seja, um código de fácil entendimento e
manutenção. Já para APIs a nomenclatura é vital para dois dos oito principios de design de
serviço: Commented [FGF7]: Link blog
 Standardized Service Contract ou Contato de Serviço Padronizado;
 Discoverability ou Visibilidade do Serviço;

Contato de Serviço Padronizado

Consiste em, como o nome diz, padronizar os contratos de serviço. Quando bem
implementado, ele proporciona os seguintes benefícios:
 Aumenta a interoperabilidade;
 Diminui o número de transformações;
 Tornar o portfólio de serviços mais consistente, fácil e intuitivo;

Visibilidade do Serviço
Em resumo, este princípio é vital para o reúso de serviços, pois não se pode reusar o que
não se conhece. Ele é apoiado pelo princípio anterior e por um repositório de serviços (leia este
post para mais detalhes). Commented [FGF8]: Link blog

O Contrato de Serviço é responsável pelos meta-dados referentes ao serviço, e o repositório

por armazenar e possibilitar buscas por palavras chave.

Desta forma é possível descobrir, rapidamente e com baixa taxa de erro, se é necessário
desenvolver um serviço candidato ou reutilizar um serviço existente.

Se ficou muito complicado, não se preocupe, pode ignorar essa parte por enquanto. Caso
tenha se interessado, escrevi um post sobre os Princípios de Design de Serviço e existe um livro Commented [FGF9]: Link blog
bem extenso que só trata disso.
Commented [FGF10]: Link amazon

É importante frisar que, na minha opinião, uma das características mais

importantes de serviços e APIs é o reúso!

Desta forma, este é um assunto que não deve ser desprezado!

Sendo mais prático, a nomenclatura pode ser dividida em duas partes, a convenção e a
nomenclatura propriamente dita:

Convenção de Nomenclatura
Cada plataforma de desenvolvimento ou tecnologia usa um conjunto de regras para nomear
seus ativos. Por exemplo se você conversar com um DBA, ele vai te falar as regras de
nomenclaturas para tabelas, colunas, índices, etc. Para APIs não é diferente.
Normalmente os projetos usam a convenção de nomenclatura usada em projetos JAVA, que
determina:
  Classes, no nosso caso Serviços: devem ser substantivos com a primeira letra de cada
palavra em maiúscula e as demais minúsculas. Ex. Pedido, ItemPedido, etc. Este padrão
também é conhecido como UpperCamelCase;
 Métodos, no nosso caso Operações: devem ser verbos com a letra minúscula em
primeiro lugar, com a primeira letra de cada palavra interna em maiúscula. Ex. criar,
alterarItem, etc. Este padrão também é conhecido como lowerCamelCase;

O mesmo padrão deve ser usado para a modelagem de Entidades, onde o nome da entidade
deve ser UpperCamelCase e o nome dos atributos lowerCamelCase. Commented [FGF11]: Colocar um tópico resumindo?