Modelando APIs com a OpenAPI Specification

A modelagem de APIs é algo crucial no projeto de um software. É a partir dela que as equipes de desenvolvimento e de testes começarão a construir o software e os cenários de testes. Contudo, contratos mal definidos podem levar a erros no momento da integração e/ou durante os testes. O objetivo desta palestra é mostrar como a modelagem de APIs é importante para a criação de contratos bem definidos e como a OpenAPI Specification auxilia na descrição de APIs que podem ser compreendida por todos os atores envolvidos e funcionando como "fonte única da verdade". A utilização da OpenAPI Specification traz inúmeros benefícios como a geração de uma documentação interativa entre outros.

Transcript

1. Marcel Gonçalves dos Santos @marcelgsantos OpenAPI Specification modelando APIs com a
2. pensandonaweb.com.br desenvolvedor web full-stack Marcel Gonçalves dos Santos @marcelgsantos
3. @phpsp phpsp.org.br
4. Interaja nas mídias sociais!
 
 - fale sobre o evento, palestrantes e conteúdo - tire fotos do evento e publique
 - interaja com outros participantes do evento - tire dúvidas ou dê feedbacks para os palestrantes
5. 1. seguir @marcelgsantos no Twitter
 2. tuitar utilizando as hashtags #OpenAPI e #TheDevConf e me marcar no tweet
 3. não vale tuíte em branco
 4. não vale retuíte Concorra a um livro da Casa do Código! 🤩
6. A onipresença das APIs no mundo moderno
7. as APIs são onipresentes nos dias atuais e estão presentes na maioria das tarefas que fazemos no dia-a-dia
8. exemplo 01 ver as notícias no início do dia pelo celular, pedir um carro por aplicativo, realizar uma transferência bancária via PIX ou fazer uma compra online
9. as APIs são a "cola digital" que permitem acelerar parcerias, facilitar a integração entre aplicações e criar novos negócios
10. exemplo 02 uma API para calcular a distância entre dois locais ou uma API que compara o preço de um produto nas maiores lojas do mercado
11. exemplo 03 criar um novo negócio que permite listar os pratos em promoção nos restaurantes da região via API
12. O que é uma API REST?
13. uma API é um conjunto de definições e protocolos usado no desenvolvimento e integração de software de aplicações
14. uma API permite a comunicação entre aplicações sem precisar saber como elas foram implementadas
15. REST significa Representational State Transfer é um estilo arquitetural criado por Roy Fielding
16. o REST são um conjunto de boas práticas denominadas restrições e é baseado no protocolo HTTP
17. ele utiliza as funcionalidades do protocolo como o conceito de URIs, verbos, cabeçalhos, status code e media types
18. uma API RESTful é aquela que está em conformidade com os conceitos REST
19. O que é a OpenAPI Specification?
20. a OpenAPI Specification é uma especificação aberta e guiada pela comunidade utilizada para a descrição de APIs
21. a OpenAPI Specification faz parte da OpenAPI Initiative e se originou a partir da Swagger specification
22. a OAS é agnóstica de linguagem de programação e é compreensível por seres humanos e máquinas
23. a partir da especificação pode-se gerar, por exemplo, uma documentação interativa, boilerplate de código e casos de testes
24. um documento OpenAPI pode descrever uma API nos formatos YAML ou JSON
25. os documentos podem ser criados manualmente ou dinamicamente através de uma aplicação (utilizando annotations, por exemplo)
26. somentes os serviços REST podem ser descritos pela OpenAPI Specification, isto é, nem todos os serviços HTTP podem ser descritos
27. a OAS não força um processo de desenvol- vimento e as abordagens conhecidas são a design-first e a code-first
28. Porque modelar ou descrever uma API REST utilizando a OAS?
29. as APIs são um elemento crucial na construção de aplicações nos dias atuais
30. são através delas que o front-end de uma aplicação se comunica com o back-end…
31. …ou que uma aplicação se comunica com outra aplicação
32. é por esse motivo que modelar e descrever uma API é tarefa importante para diversos atores como desenvolvedores back-end, front-end e testers
33. mas acontecem situações como:
 
 A: Quais serão os dados retornados pela API de pedidos? B: Os dados serão id, cliente, itens, valor total e status. A: Ok, vou implementar a minha parte. B: Ok, vou implementar a minha parte também.
35. isso pode ocasionar problemas como:
 
 - problema ao integrar o front-end e back-end
 - incompatibilidade de tipos do payload
 - payload de erro não padronizado
 - esquecer de tratar status code não previstos
36. para evitar estes tipos de problemas reco- menda-se utilizar a abordagem design-first
 para modelar e descrever APIs
37. a abordagem design-first permite planeja- mento prévio e compreensão robusta entre desenvolvedores e especialistas de domínio de como a API deve funcionar
38. ela permite também a utilização da linguagem ubíqua do domínio para modelar a API, isto é, utilizá-la em urls, query strings, payloads e mensagens de erro
39. e ao descrever a API utilizando a OpenAPI Specification tem-se uma linguagem comum entre os vários atores envolvidos
40. a OAS pela sua facilidade de leitura para humanos e máquinas torna-se a fonte única da verdade na descrição de APIs
41. além disso pode-se gerar automaticamente, por exemplo, uma documentação interativa, boilerplate de código e casos de testes
42. Caso de Uso
 API para gerenciamento
 de palestras
43. criar uma API REST para o gerenciamento de palestras de um evento de tecnologia
44. uma palestra deverá ser associada a um palestrante e ter os campos: título, descrição, nível, duração, data e horário e se possui live coding
45. !// GET /talks/5049c8b4-4e46-4a41-b52e-83ef8a315a76
 { "id": "5049c8b4-4e46-4a41-b52e-83ef8a315a76", "speaker_id": "7a728c56-b966-4dcc-adc5-57c0f807392c", "title": "Modelando APIs com a OpenAPI Specification", "description": "A modelagem de APIs é algo crucial no…”, "level": "beginner", "duration": 30, "presentation_date": "2021-06-08 11:30", "live_coding": true }
46. é possível filtrar as palestras por nível, data de apresentação e se possui live coding
47. !// GET /talks?level=beginner&date=2021-06-08&live_coding=true
 [ { "id": "5049c8b4-4e46-4a41-b52e-83ef8a315a76", "speaker_id": "7a728c56-b966-4dcc-adc5-57c0f807392c", "title": "Modelando APIs com a OpenAPI Specification", "description": "A modelagem de APIs é algo crucial no!!...", "level": "beginner", "duration": 30, "presentation_date": "2021-06-08 11:30", "live_coding": true } ]
48. não é o objetivo da palestra ensinar sobre boas práticas ou design de APIs
49. para isso, deixo como referência as ótimas palestras do Kleber Bacilli e do Thiago Lima
 
 - Design de APIs RESTful - youtu.be/psLrAsdHltQ
 - REST API com Thiago Lima - youtu.be/59iOK5TE2CY
50. Modelando uma API REST utilizando a OpenAPI Specification
51. um documento OpenAPI pode ser composto por um único ou vários arquivos
52. recomenda-se que o documento raiz tenha o nome openapi.yaml ou openapi.json
53. um documento OpenAPI que descreve uma API REST deve ter obrigatoriamente os campos openapi, info e paths
54. openapi - indica a versão da especificação
 info - possui informações gerais como título, descrição e versão da API
 paths - permite descrever os entrypoints da API
55. exemplo 06 um documento OpenAPI mínimo
56. openapi: 3.0.1 info: title: A minimal OpenAPI document version: 0.0.1 paths: {}
57. exemplo 07 modelagem inicial do caso de uso
58. openapi: 3.0.1 info: title: The Developer's Conference API description: API para o gerenciamento de palestras do TDC contact: name: Marcel dos Santos url: http:!//example.com/support email: marcelgsantos@gmail.com version: 0.1.0 paths: {}
59. pode-se utilizar ferramentas especializadas para a descrição e modelagem de APIs como o Swagger Editor e o Stoplight
60. contudo, pode-se utilizar também um editor de texto como o VSCode ou uma IDE como o IntelliJ ou PhpStorm
61. exemplo 08 preview da modelagem inicial do caso de uso
63. o campo servers permite descrever um ou mais servidores de uma API
64. exemplo 09
 descrição dos servidores disponíveis no caso de uso
65. servers: - url: http:!//api-dev.example.com description: Development Server - url: https:!//api-hmg.example.com description: Homolog Server - url: https:!//api.example.com description: Production Server
67. o campo paths é onde são descritos os endpoints e suas operações
68. um path deve começar com uma barra / e pode utilizar placeholders para valores como, por exemplo, /talks/{uuid}
69. ele é concatenado com url do servidor para construir a url completa
70. um path possui campos fixos que representam as operações como get, 
 post, put e delete
71. as operações podem ter os campos summary, description, tags, operationId que são responsáveis por descrever, organizar e identificar as mesmas
72. exemplo 10
 modelagem dos paths e operações do caso de uso
73. paths: /talks/{uuid}: put: summary: altera os dados de uma palestra operationId: updateTalk tags: - talks parameters: # !!... requestBody: # !!... responses: # !!...
74. e também podem ter os campos parameters, requestBody e responses que permitem definir os parâmetros, o corpo da requisição e as respostas
75. o campo parameters pode ter os campos name, in, description e required e permite descrever os parâmetros que estão na url, query string, cabeçalho ou cookie
76. exemplo 11
 modelagem dos parâmetros de uma requisição do caso de uso
77. paths: /talks/{uuid}: put: summary: altera os dados de uma palestra operationId: updateTalk parameters: - name: uuid in: path description: uuid da palestra required: true schema: type: string format: uuid requestBody: # !!... responses: # !!...
78. o campo requestBody possui os campos fixos description, content e required e permite descrever o corpo da requisição
79. o campo content é obrigatório e a sua chave refere-se a um media type como application/json e o seu valor a um media type object
80. exemplo 12
 modelagem do corpo da requisição do caso de uso
81. paths: /talks/{uuid}: put: summary: altera os dados de uma palestra operationId: updateTalk parameters: # !!... requestBody: description: corpo da requisição required: true content: application/json: schema: $ref: '#/components/schemas/Talk' responses: # !!...
82. o campo responses possui chaves que representam os status code possíveis para a resposta
83. e cada status code possui os campos description e content e permite descrever o corpo da resposta
84. exemplo 13
 modelagem do corpo da resposta do caso de uso
85. paths: /talks/{uuid}: put: summary: altera os dados de uma palestra operationId: updateTalk parameters: # !!... requestBody: # !!... responses: '200': description: Ok '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/DomainError'
86. um schema permite definir tipos de dados e podem ser objetos, primitivos ou arrays
87. ele pode ser utilizado para definir o tipo de dados de um parâmetro, corpo de requisição ou corpo de resposta
88. exemplo 14
 utilização de um schema para definir um tipo de um parâmetro do caso de uso
89. paths: /talks: get: summary: listar palestras parameters: - name: level in: query description: nível da palestra required: false schema: type: string enum: - beginner - intermediate - advanced
90. pode-se criar schemas mais complexos e que podem ser reutilizados em várias partes da documentação
91. exemplo 15
 criação de um schema para ser reutilizado do caso de uso
92. components: schemas: Talk: type: object properties: id: type: string format: uuid speaker_id: type: string format: uuid title: type: string description: type: string level: type: string type: string description: type: string level: type: string enum: - beginner - intermediate - advanced duration: type: integer format: int32 presentation_date: type: string format: datetime has_live_coding: type: boolean
94. Conclusão
95. a descrição e modelagem de APIs utilizando a abordagem design-first é importante…
96. …para que todos os atores envolvidos façam o planejamento antecipado e tenham uma compreensão robusta sobre a API
97. ela permite com que possíveis erros sejam antecipados e efeitos indesejados sejam evitados como problemas na integração
98. a OpenAPI Specification funciona como linguagem única para a descrição de APIs REST e é facilmente legível por humanos e máquina
99. isso faz com que o documento OpenAPI se torna a fonte única da verdade sobre a API na sua aplicação
100. além de permitir a geração automática de boilerplate de código, documentação interativa ou casos de testes
101. essa apresentação apenas arranhou a superfície quando se fala da OAS e suas possibilidades
102. recomenda-se aprofundar os estudos para entender melhor os detalhes da OAS como media types, recursos de segurança e schemas mais complexos
103. vá em frente e divirta-se!
104. Referências
105. bit.ly/palestra-openapi-specification
106. Avalie!
107. @marcelgsantos speakerdeck.com/marcelgsantos Obrigado. Perguntas?