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
   

   View Slide

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

   View Slide

3. @phpsp
   phpsp.org.br
   

   View Slide

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
   

   View Slide

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

   View Slide

6. A onipresença das APIs
   no mundo moderno
   

   View Slide

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

   View Slide

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
   

   View Slide

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

   View Slide

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
    

    View Slide

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

    View Slide

12. O que é uma
    API REST?
    

    View Slide

13. uma API é um conjunto de definições e
    protocolos usado no desenvolvimento e
    integração de software de aplicações
    

    View Slide

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

    View Slide

15. REST significa Representational State
    Transfer é um estilo arquitetural criado por
    Roy Fielding
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

19. O que é a OpenAPI
    Specification?
    

    View Slide

20. a OpenAPI Specification é uma especificação
    aberta e guiada pela comunidade utilizada
    para a descrição de APIs
    

    View Slide

21. a OpenAPI Specification faz parte da
    OpenAPI Initiative e se originou a partir da
    Swagger specification
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

26. somentes os serviços REST podem ser
    descritos pela OpenAPI Specification, isto é,
    nem todos os serviços HTTP podem ser
    descritos
    

    View Slide

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
    

    View Slide

28. Porque modelar ou
    descrever uma API REST
    utilizando a OAS?
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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.
    

    View Slide

34. View Slide

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
    

    View Slide

36. para evitar estes tipos de problemas reco-
    menda-se utilizar a abordagem design-first

    para modelar e descrever APIs
    

    View Slide

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
    

    View Slide

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
    

    View Slide

39. e ao descrever a API utilizando a OpenAPI
    Specification tem-se uma linguagem
    comum entre os vários atores envolvidos
    

    View Slide

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
    

    View Slide

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

    View Slide

42. Caso de Uso

    API para gerenciamento

    de palestras
    

    View Slide

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

    View Slide

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
    

    View Slide

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
    }
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

50. Modelando uma API REST
    utilizando a OpenAPI
    Specification
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

55. exemplo 06
    um documento OpenAPI mínimo
    

    View Slide

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

    View Slide

57. exemplo 07
    modelagem inicial do caso de uso
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

61. exemplo 08
    preview da modelagem inicial do caso de
    uso
    

    View Slide

62. View Slide

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

    View Slide

64. exemplo 09

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

    View Slide

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
    

    View Slide

66. View Slide

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

    View Slide

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

    View Slide

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

    View Slide

70. um path possui campos fixos que
    representam as operações como get, 

    post, put e delete
    

    View Slide

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

    View Slide

72. exemplo 10

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

    View Slide

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

    View Slide

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
    

    View Slide

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
    

    View Slide

76. exemplo 11

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

    View Slide

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

    View Slide

78. o campo requestBody possui os campos
    fixos description, content e required e
    permite descrever o corpo da requisição
    

    View Slide

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
    

    View Slide

80. exemplo 12

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

84. exemplo 13

    modelagem do corpo da resposta do caso
    de uso
    

    View Slide

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'
    

    View Slide

86. um schema permite definir tipos de dados e
    podem ser objetos, primitivos ou arrays
    

    View Slide

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

    View Slide

88. exemplo 14

    utilização de um schema para definir um tipo
    de um parâmetro do caso de uso
    

    View Slide

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
    

    View Slide

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

    View Slide

91. exemplo 15

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

    View Slide

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
    

    View Slide

93. View Slide

94. Conclusão
    

    View Slide

95. a descrição e modelagem de APIs
    utilizando a abordagem design-first é
    importante…
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

     View Slide

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

     View Slide

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

     View Slide

103. vá em frente e divirta-se!
     

     View Slide

104. Referências
     

     View Slide

105. bit.ly/palestra-openapi-specification
     

     View Slide

106. Avalie!
     

     View Slide

107. @marcelgsantos
     speakerdeck.com/marcelgsantos
     Obrigado.
     Perguntas?
     

     View Slide