O documento discute as melhores práticas para APIs, destacando a importância de uma estrutura bem definida, como REST e SOAP. Ele enfatiza princípios fundamentais do REST, como statelessness e uso de URIs legíveis, e compara REST com SOAP em termos de eficiência e complexidade. A conclusão sugere que seguir essas práticas resulta em sistemas mais portáveis, escaláveis e de fácil manutenção.

1. API Best Practices
Daniel Christofolli
3ª Apresentação

2. Application Programming Interface
● Conjunto de especificações que são utilizadas para fazer a interface entre
os diferentes programas de software que rodam em uma única aplicação
ou hardware;
● Semelhante ao modelo SaaS (Software as a Service), uma vez que não
temos que começar do zero cada vez que fazemos um programa;

3. Simple Object Access Protocol
É um protocolo baseado em XML para troca de informações estruturadas em
uma plataforma descentralizada e distribuída.

5. ● Envelope => define o que está na mensagem e como processá-la
● Header => conjunto de regras codificadas para expressar instâncias do tipos de
dados definidos na aplicação
● Body => instruções para representar chamadas de procedimentos e respostas.
Estrutura

6. Representational State Transfer
Conjunto de práticas que ajudam a desenvolver web services bem
estruturados. Suporta vários formatos, incluindo JSON, HTML e XML

7. Princípios
● Stateless => a mensagem HTTP carrega todas as informações
necessárias para compreender a requisição.
● Operações bem definidas => POST, GET, PUT e DELETE
● Sintaxe Universal => cada recurso é unicamente direcionado através da
sua URI
● Hipermídia => é possível navegar entre os recursos seguindo links
● Interface cliente/servidor uniforme => Identificação dos recursos,
representação dos recursos, mensagens auto-descritivas e hipermídia

8. ● Requisição => composta pelo método HTTP e pela URI
● Body => conteúdo da requisição ou da resposta;
● JSON => formato simples, baseado em key/ value;
Estrutura REST

9. Identificação dos recursos
● Recurso = Tudo que é gerenciado por uma API;
● URI = Endereço completo de um recurso

10. Uniform Resource Identifier
● Utilize URI’s legíveis
● Utilize o mesmo padrão de URI na identificação dos recursos
● Evite adicionar na URI a operação a ser realizada no recurso
● Evite adicionar na URI o formato desejado da representação do recurso
● Evite alterações nas URI’s

11. Exemplos de URIs
http://servicorest.com.br/produtos;
http://servicorest.com.br/clientes;
http://servicorest.com.br/clientes/57;
http://servicorest.com.br/vendas.
http://servicorest.com.br/produto (Singular);
http://servicorest.com.br/clientes (Plural);
http://servicorest.com.br/processosAdministrativos (Camel
Case);
http://servicorest.com.br/processos_judiciais (Snake Case).
http://servicorest.com.br/produtos/cadastrar;
http://servicorest.com.br/clientes/10/excluir;
http://servicorest.com.br/vendas/34/atualizar.
http://servicorest.com.br/produtos/xml;
http://servicorest.com.br/clientes/112?formato=json.

12. Hypermedia as the Engine of Application State
● Navegação dinâmica entre endpoints através de links adicionados aos
dados
● Essa combinação representa o estado do sistema
● Reforça o stateless => O servidor não precisa manter registro da sessão: o
próprio cliente sabe que as únicas transições possíveis são aquelas para
as quais existe um link disponível

13. Exemplo de Hateoas
● rel => Nesse caso o link faz referência à própria pessoa;
● href => URL completa que define um único recurso
Objeto Cliente
JSON simples
JSON Hateoas

14. SOAP x REST
● SOAP ainda é muito usado em sistemas legados;
● A curva de aprendizado é menor no REST;
● O stateless e o uso de JSON tornam o REST mais eficiente;
● REST trabalha com vários formatos de mensagens, SOAP só usa XML;
● REST usa operações baseadas em recursos, usando requisições HTTP;
● REST permite o uso de repetição de envio de mensagens;

15. Conclusão
Ao adotarmos boas práticas em nossos projetos, teremos sistemas portáveis,
escaláveis e desacoplados, facilitando a manutenção e reutilização dos
nossos códigos