Modelando APIs com a OpenAPI Specification

Slide 1

Slide 1 text

Marcel Gonçalves dos Santos @marcelgsantos OpenAPI Specification modelando APIs com a

Slide 2

Slide 2 text

pensandonaweb.com.br desenvolvedor web full-stack Marcel Gonçalves dos Santos @marcelgsantos

Slide 3

Slide 3 text

@phpsp phpsp.org.br

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

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! 🤩

Slide 6

Slide 6 text

A onipresença das APIs no mundo moderno

Slide 7

Slide 7 text

as APIs são onipresentes nos dias atuais e estão presentes na maioria das tarefas que fazemos no dia-a-dia

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

as APIs são a "cola digital" que permitem acelerar parcerias, facilitar a integração entre aplicações e criar novos negócios

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

exemplo 03 criar um novo negócio que permite listar os pratos em promoção nos restaurantes da região via API

Slide 12

Slide 12 text

O que é uma API REST?

Slide 13

Slide 13 text

uma API é um conjunto de deﬁnições e protocolos usado no desenvolvimento e integração de software de aplicações

Slide 14

Slide 14 text

uma API permite a comunicação entre aplicações sem precisar saber como elas foram implementadas

Slide 15

Slide 15 text

REST signiﬁca Representational State Transfer é um estilo arquitetural criado por Roy Fielding

Slide 16

Slide 16 text

o REST são um conjunto de boas práticas denominadas restrições e é baseado no protocolo HTTP

Slide 17

Slide 17 text

ele utiliza as funcionalidades do protocolo como o conceito de URIs, verbos, cabeçalhos, status code e media types

Slide 18

Slide 18 text

uma API RESTful é aquela que está em conformidade com os conceitos REST

Slide 19

Slide 19 text

O que é a OpenAPI Speciﬁcation?

Slide 20

Slide 20 text

a OpenAPI Speciﬁcation é uma especiﬁcação aberta e guiada pela comunidade utilizada para a descrição de APIs

Slide 21

Slide 21 text

a OpenAPI Speciﬁcation faz parte da OpenAPI Initiative e se originou a partir da Swagger speciﬁcation

Slide 22

Slide 22 text

a OAS é agnóstica de linguagem de programação e é compreensível por seres humanos e máquinas

Slide 23

Slide 23 text

a partir da especiﬁcação pode-se gerar, por exemplo, uma documentação interativa, boilerplate de código e casos de testes

Slide 24

Slide 24 text

um documento OpenAPI pode descrever uma API nos formatos YAML ou JSON

Slide 25

Slide 25 text

os documentos podem ser criados manualmente ou dinamicamente através de uma aplicação (utilizando annotations, por exemplo)

Slide 26

Slide 26 text

somentes os serviços REST podem ser descritos pela OpenAPI Speciﬁcation, isto é, nem todos os serviços HTTP podem ser descritos

Slide 27

Slide 27 text

a OAS não força um processo de desenvolvimento e as abordagens conhecidas são a design-ﬁrst e a code-ﬁrst

Slide 28

Slide 28 text

Porque modelar ou descrever uma API REST utilizando a OAS?

Slide 29

Slide 29 text

as APIs são um elemento crucial na construção de aplicações nos dias atuais

Slide 30

Slide 30 text

são através delas que o front-end de uma aplicação se comunica com o back-end…

Slide 31

Slide 31 text

…ou que uma aplicação se comunica com outra aplicação

Slide 32

Slide 32 text

é por esse motivo que modelar e descrever uma API é tarefa importante para diversos atores como desenvolvedores back-end, front-end e testers

Slide 33

Slide 33 text

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.

Slide 34

Slide 34 text

No content

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

para evitar estes tipos de problemas recomenda-se utilizar a abordagem design-ﬁrst  para modelar e descrever APIs

Slide 37

Slide 37 text

a abordagem design-ﬁrst permite planejamento prévio e compreensão robusta entre desenvolvedores e especialistas de domínio de como a API deve funcionar

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

e ao descrever a API utilizando a OpenAPI Speciﬁcation tem-se uma linguagem comum entre os vários atores envolvidos

Slide 40

Slide 40 text

a OAS pela sua facilidade de leitura para humanos e máquinas torna-se a fonte única da verdade na descrição de APIs

Slide 41

Slide 41 text

além disso pode-se gerar automaticamente, por exemplo, uma documentação interativa, boilerplate de código e casos de testes

Slide 42

Slide 42 text

Caso de Uso  API para gerenciamento  de palestras

Slide 43

Slide 43 text

criar uma API REST para o gerenciamento de palestras de um evento de tecnologia

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

!// 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 }

Slide 46

Slide 46 text

é possível ﬁltrar as palestras por nível, data de apresentação e se possui live coding

Slide 47

Slide 47 text

!// 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 } ]

Slide 48

Slide 48 text

não é o objetivo da palestra ensinar sobre boas práticas ou design de APIs

Slide 49

Slide 49 text

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

Slide 50

Slide 50 text

Modelando uma API REST utilizando a OpenAPI Speciﬁcation

Slide 51

Slide 51 text

um documento OpenAPI pode ser composto por um único ou vários arquivos

Slide 52

Slide 52 text

recomenda-se que o documento raiz tenha o nome openapi.yaml ou openapi.json

Slide 53

Slide 53 text

um documento OpenAPI que descreve uma API REST deve ter obrigatoriamente os campos openapi, info e paths

Slide 54

Slide 54 text

openapi - indica a versão da especiﬁcação  info - possui informações gerais como título, descrição e versão da API  paths - permite descrever os entrypoints da API

Slide 55

Slide 55 text

exemplo 06 um documento OpenAPI mínimo

Slide 56

Slide 56 text

openapi: 3.0.1 info: title: A minimal OpenAPI document version: 0.0.1 paths: {}

Slide 57

Slide 57 text

exemplo 07 modelagem inicial do caso de uso

Slide 58

Slide 58 text

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: {}

Slide 59

Slide 59 text

pode-se utilizar ferramentas especializadas para a descrição e modelagem de APIs como o Swagger Editor e o Stoplight

Slide 60

Slide 60 text

contudo, pode-se utilizar também um editor de texto como o VSCode ou uma IDE como o IntelliJ ou PhpStorm

Slide 61

Slide 61 text

exemplo 08 preview da modelagem inicial do caso de uso

Slide 62

Slide 62 text

No content

Slide 63

Slide 63 text

o campo servers permite descrever um ou mais servidores de uma API

Slide 64

Slide 64 text

exemplo 09  descrição dos servidores disponíveis no caso de uso

Slide 65

Slide 65 text

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

Slide 66

Slide 66 text

No content

Slide 67

Slide 67 text

o campo paths é onde são descritos os endpoints e suas operações

Slide 68

Slide 68 text

um path deve começar com uma barra / e pode utilizar placeholders para valores como, por exemplo, /talks/{uuid}

Slide 69

Slide 69 text

ele é concatenado com url do servidor para construir a url completa

Slide 70

Slide 70 text

um path possui campos ﬁxos que representam as operações como get,   post, put e delete

Slide 71

Slide 71 text

as operações podem ter os campos summary, description, tags, operationId que são responsáveis por descrever, organizar e identiﬁcar as mesmas

Slide 72

Slide 72 text

exemplo 10  modelagem dos paths e operações do caso de uso

Slide 73

Slide 73 text

paths: /talks/{uuid}: put: summary: altera os dados de uma palestra operationId: updateTalk tags: - talks parameters: # !!... requestBody: # !!... responses: # !!...

Slide 74

Slide 74 text

e também podem ter os campos parameters, requestBody e responses que permitem deﬁnir os parâmetros, o corpo da requisição e as respostas

Slide 75

Slide 75 text

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

Slide 76

Slide 76 text

exemplo 11  modelagem dos parâmetros de uma requisição do caso de uso

Slide 77

Slide 77 text

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: # !!...

Slide 78

Slide 78 text

o campo requestBody possui os campos ﬁxos description, content e required e permite descrever o corpo da requisição

Slide 79

Slide 79 text

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

Slide 80

Slide 80 text

exemplo 12  modelagem do corpo da requisição do caso de uso

Slide 81

Slide 81 text

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: # !!...

Slide 82

Slide 82 text

o campo responses possui chaves que representam os status code possíveis para a resposta

Slide 83

Slide 83 text

e cada status code possui os campos description e content e permite descrever o corpo da resposta

Slide 84

Slide 84 text

exemplo 13  modelagem do corpo da resposta do caso de uso

Slide 85

Slide 85 text

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'

Slide 86

Slide 86 text

um schema permite deﬁnir tipos de dados e podem ser objetos, primitivos ou arrays

Slide 87

Slide 87 text

ele pode ser utilizado para deﬁnir o tipo de dados de um parâmetro, corpo de requisição ou corpo de resposta

Slide 88

Slide 88 text

exemplo 14  utilização de um schema para deﬁnir um tipo de um parâmetro do caso de uso

Slide 89

Slide 89 text

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

Slide 90

Slide 90 text

pode-se criar schemas mais complexos e que podem ser reutilizados em várias partes da documentação

Slide 91

Slide 91 text

exemplo 15  criação de um schema para ser reutilizado do caso de uso

Slide 92

Slide 92 text

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

Slide 93

Slide 93 text

No content

Slide 94

Slide 94 text

Conclusão

Slide 95

Slide 95 text

a descrição e modelagem de APIs utilizando a abordagem design-ﬁrst é importante…

Slide 96

Slide 96 text

…para que todos os atores envolvidos façam o planejamento antecipado e tenham uma compreensão robusta sobre a API

Slide 97

Slide 97 text

ela permite com que possíveis erros sejam antecipados e efeitos indesejados sejam evitados como problemas na integração

Slide 98

Slide 98 text

a OpenAPI Speciﬁcation funciona como linguagem única para a descrição de APIs REST e é facilmente legível por humanos e máquina

Slide 99

Slide 99 text

isso faz com que o documento OpenAPI se torna a fonte única da verdade sobre a API na sua aplicação

Slide 100

Slide 100 text

além de permitir a geração automática de boilerplate de código, documentação interativa ou casos de testes

Slide 101

Slide 101 text

essa apresentação apenas arranhou a superfície quando se fala da OAS e suas possibilidades

Slide 102

Slide 102 text

recomenda-se aprofundar os estudos para entender melhor os detalhes da OAS como media types, recursos de segurança e schemas mais complexos