O documento apresenta uma introdução sobre APIs e a abordagem API First. Explica que uma API First significa conceber a API como o primeiro elemento da estratégia de produto, construindo-a de forma independente para ser consumida da melhor maneira pelos clientes. Também discute diretrizes e boas práticas para implementar uma abordagem API First usando a especificação OpenAPI.

1. Construindo APIs
com a Open API
Spec e Java

2. Raphael Rodrigues
BsC em Ciência da Computação UFRJ;
+- 15 anos na área de desenvolvimento de software;
Javeiro desde então;
Diferentes papéis:
× Dev, Tech Lead, IT Architect;
× Pre-sales, Consulting;
× Instructor;
× Speaker;
2
Olá!

3. APIs?

4. APIs?
"O termo API aparece pela primeira vez em
um artigo acadêmico em 1968"
https://dl.acm.org/purchase.cfm?id=1476661

10. 1.API Economy
O que é uma abordagem API First?

12. "Uma empresa sem API para interconectividade é como viver
antes da era da internet."
"Em 2020 ~37Bi de dispositivos serão capazes de conectar com
API";

15. 1.
API First
O que é uma abordagem API
First?

16. API First
× Conceber sua API como sendo o
primeiro elemento da sua estratégia de
produto ou serviço;
× Significa construir a API a partir do
zero para ser consumido da melhor
maneira para os seus clientes;
16

17. #1 Sua API é a
primeira interface
do usuário com a
aplicação
17

18. 18
#2 Sua API é
concebida
primeiro, antes da
implementação

19. 19
#3 Sua API deve
ser bem descrita

20. 20

21. O uso de Hypermedia links permite
descobrir outros recursos presentes na
API.
APIs auto-
descritivas
21

22. 3.
Adoção de API First
com OAS
How hard can it be?

23. Diretrizes
23
Planejamento
Como sua organização ou time planejam essa nova abordagem?
Identifique quem são seus APIs stakeholders;
Identifique quem são seus API customers;
Organize o time de governança;
Estabeleça um processo que seja repetível, realístico e leve;

24. Processo Paypal
24
https://www.infoq.com/articles/paypal-api-first-part1/

25. Diretrizes
25
Por que?
Quanto mais APIs são adicioanadas, é importante
garantir que elas serão consistentes entre elas;
APIs que tem padrões comuns serão mais fáceis de
integrá-las;
Novas APIs não precisa reinventar a roda;

26. Diretrizes
26

27. • Use substantivos não verbos
• Ex:
• GET /products
• GET /getProducts
• Use parâmetros no path ou query string
• Ex:
• GET /products/{id}
• GET /productsById
• PUT ou PATCH ? 27
Guidelines - Exemplos

28. • Versione suas APIs;
• Paginação;
• Ex: /products?limit=25&offset=50
• Indique quais formatos sua API suporta
• JSON obrigatório;
• Códigos de erro não se resumem a 200 e 500;
• Customize os erros com json
28
Guidelines - Exemplos

29. 29
https://www.openapis.org/
An open source collaborative project of the Linux Foundation

30. Membros
30

31. Histórico
31
2010
Swagger
development
2015
SmartBear
acquired
Reverb
Technologies
End 2015
create Open
Api Initiative
2016
Swagger
spec was
renemad to
OpenAPI
Spec (OAS)
2017 Open
API Initiative
released
version 3.0.0

32. Implementações
32
Ferramentas de baixo nível;
Editores;
Interfaces;
Servidores para mock;
Implementações de back-end;
Implementações para cliente;
Geradores de código;
https://github.com/OAI/OpenAPI-
Specification/blob/master/IMPLEMENTATIONS.md
https://openapi.tools/

33. Sugestão
33
API design;
Plataforma de documentação;
Desenhada para times colaborarem de forma consistente e
disciplinada na elaboração de APIs;

34. Place your screenshot here
34
Desktop project
Show and explain
your web, app or
software projects
using these gadget
templates.

35. 35
https://swagger.io/specification/
OpenAPI Specification

36. • Especifica como descrever sua API;
• API significa coleção de requisições;
• Qual servidor?
• Qual segurança?
• Quais requisições estão disponíveis na API?
• Quais dados de entrada são esperados em uma
requisição?
• Quais dados de saída são esperados em uma
requisição?
36
Open API Spec

37. • Descrita em YAML ou JSON;
• Correntemente na versão 3.0.2;
• Permite gerar documentação
• Elementos description;
• Elementos example e examples;
• Aceita markdown;
37
Open API Spec

38. • https://github.com/OAI/OpenAPI-
Specification/blob/master/examples/v3.0/petstore
.yaml
38
Open API Spec - Exemplo

39. 39

40. 40
Open API Spec - Exemplo

41. Obrigado!
raphaufrj@gmail.com
https://www.linkedin.com/in/raphaelrodrigues2
41