Simplificando APIs Rest

Apresentação fala sobre alguns padrão que devemos tentar seguir para facilitar a integração de novos clientes, evolução e manutenção de uma API.

Transcript

1. Simplificando APIs REST
2. Aplicações Aplicações Aplicações
3. Aplicações Aplicações Aplicações
4. Aplicações Aplicações Aplicações
5. Aplicações Aplicações Aplicações
6. Aplicações Aplicações Aplicações APIs APIs
7. Application Programming Interface
8. Mattheus Cassundé Software Engineer cassunde.com.br
9. Mattheus Cassundé Software Engineer cassunde.com.br
10. Mattheus Cassundé Software Engineer cassunde.com.br
11. Mattheus Cassundé Software Engineer cassunde.com.br
12. Application Programming Interface
13. • Simplificar Integrações • Impulsionar Novos negócios Application Programming Interface
14. • Simplificar Integrações • Impulsionar Novos negócios Application Programming Interface
17. API
18. API
19. API
20. Aplicações Aplicações n… API
21. REST
22. Representational State Transfer REST
23. Representational State Transfer REST RESTful Segue firme os conceitos do REST
24. Representational State Transfer REST RESTful Segue firme os conceitos do REST
25. Request Response
26. ENDEREÇO CABEÇALHO CORPO Request Response
27. ENDEREÇO CABEÇALHO CORPO CABEÇALHO CORPO STATUS Request Response
28. Request Response aplicação aplicação
29. Request Response aplicação aplicação cliente servidor
30. Request Response aplicação sua aplicação
31. Request Response aplicação sua aplicação
32. Response aplicação sua aplicação Request
33. • URI • Recursos • Operações • Versionamento • Media Types • Status & Erros Code • Filtro e Paginações • Segurança (Inicial) 8 Padrões
34. • URI • Recursos • Operações • Versionamento • Media Types • Status & Erros Code • Filtro e Paginações • Segurança (Inicial) 8 Padrões
35. URL & URI
36. URL & URI https://localhost:8080/suaplicacao/v1/orders/{id}
37. URL & URI https://localhost:8080/suaplicacao/v1/orders/{id}
38. URL & URI https://localhost:8080/suaplicacao/v1/orders/{id} URI
39. URL & URI https://localhost:8080/suaplicacao/v1/orders/{id} URI HOST
40. URL & URI https://localhost:8080/suaplicacao/v1/orders/{id} URI HOST
41. URL & URI https://localhost:8080/suaplicacao/v1/orders/{id} URI URL HOST
42. • URI • Recursos • Operações • Versionamento • Media Types • Status & Erros Code • Filtro e Paginações • Segurança (Inicial) 8 Padrões
43. Recursos
44. • Funcionalidades bem definidas oferecidas pela API • Como uma instância de um objeto Recursos
45. • Funcionalidades bem definidas oferecidas pela API • Como uma instância de um objeto Recursos
46. • Funcionalidades bem definidas oferecidas pela API • Como uma instância de um objeto ◦ Métodos fixos (POST, GET, PUT, DELETE) ◦ Sempre o mesmo corpo nas repostas Recursos
48. Escutar música nas rádios
49. Escutar música nas rádios
50. Aumentar o volume Mudar estação Escutar música nas rádios
51. Aumentar o volume Mudar estação Escutar música nas rádios api
52. Aumentar o volume Mudar estação Escutar música nas rádios recurso recurso api
53. Aumentar o volume Mudar estação Escutar música nas rádios recurso recurso api end-point end-point
54. Recurso: Pedidos
55. • Criar pedido • Cancelar um pedido • Buscar um pedido • Atualizar um pedido Recurso: Pedidos
56. • Criar pedido • Cancelar um pedido • Buscar um pedido • Atualizar um pedido Recurso: Pedidos • /orders
57. • Criar pedido • Cancelar um pedido • Buscar um pedido • Atualizar um pedido Recurso: Pedidos • /orders
58. • Criar pedido • Cancelar um pedido • Buscar um pedido • Atualizar um pedido Recurso: Pedidos • /orders • /orders/{id} • /orders/{id} • /orders/{id}
59. • Criar pedido • Cancelar um pedido • Buscar um pedido • Atualizar um pedido Recurso: Pedidos • /orders • /orders/{id} • /orders/{id} • /orders/{id}
60. Criar pedido
61. Criar pedido __?__ /orders
62. Criar pedido __?__ /orders
63. Criar pedido POST /orders
64. Sempre retorna um identificador Criar pedido POST /orders
65. Sempre retorna um identificador Criar pedido
66. Sempre retorna um identificador Criar pedido
67. Sempre retorna um identificador Criar pedido
68. Sempre retorna um identificador Criar pedido
69. Sempre retorna um identificador Criar pedido
70. Sempre retorna um identificador Criar pedido
71. Sempre retorna um identificador Criar pedido
72. Sempre retorna um identificador Criar pedido
73. • Criar pedido • Cancelar um pedido • Buscar um pedido • Atualizar um pedido Recurso: Pedidos • /orders • /orders/{id} • /orders/{id} • /orders/{id}
74. • URI • Recursos • Operações • Versionamento • Media Types • Status & Erros Code • Filtro e Paginações • Segurança (Inicial) 8 Padrões
75. Operações
76. Operações - Verbos HTTP GET POST PUT PATCH DELETE
77. Operações - Verbos HTTP GET POST PUT PATCH DELETE Buscas
78. Operações - Verbos HTTP GET POST PUT PATCH DELETE Buscas Criação
79. Operações - Verbos HTTP GET POST PUT PATCH DELETE Buscas Criação Atualiza todo o objeto
80. Operações - Verbos HTTP GET POST PUT PATCH DELETE Buscas Criação Atualiza todo o objeto Atualiza uma parte do objeto
81. Operações - Verbos HTTP GET POST PUT PATCH DELETE Buscas Criação Atualiza todo o objeto Atualiza uma parte do objeto Remove um objeto
82. Operações - Verbos HTTP RECURSO GET POST PUT PATCH DELETE /orders /orders/123
83. Operações - Verbos HTTP RECURSO GET POST PUT PATCH DELETE /orders Retornar todos os pedidos /orders/123
84. Operações - Verbos HTTP RECURSO GET POST PUT PATCH DELETE /orders Retornar todos os pedidos Criar um pedido /orders/123
85. Operações - Verbos HTTP RECURSO GET POST PUT PATCH DELETE /orders Retornar todos os pedidos Criar um pedido NADA /orders/123
86. Operações - Verbos HTTP RECURSO GET POST PUT PATCH DELETE /orders Retornar todos os pedidos Criar um pedido NADA NADA NADA /orders/123
87. Operações - Verbos HTTP RECURSO GET POST PUT PATCH DELETE /orders Retornar todos os pedidos Criar um pedido NADA NADA NADA /orders/123 Retorna pedido 123
88. Operações - Verbos HTTP RECURSO GET POST PUT PATCH DELETE /orders Retornar todos os pedidos Criar um pedido NADA NADA NADA /orders/123 Retorna pedido 123 NADA
89. Operações - Verbos HTTP RECURSO GET POST PUT PATCH DELETE /orders Retornar todos os pedidos Criar um pedido NADA NADA NADA /orders/123 Retorna pedido 123 NADA Atualiza todo pedido 123
90. Operações - Verbos HTTP RECURSO GET POST PUT PATCH DELETE /orders Retornar todos os pedidos Criar um pedido NADA NADA NADA /orders/123 Retorna pedido 123 NADA Atualiza todo pedido 123 Atualiza uma parte do pedido 123
91. Operações - Verbos HTTP RECURSO GET POST PUT PATCH DELETE /orders Retornar todos os pedidos Criar um pedido NADA NADA NADA /orders/123 Retorna pedido 123 NADA Atualiza todo pedido 123 Atualiza uma parte do pedido 123 Remove o pedido 123
92. POST - Criação POST /orders
93. { "product":"beer", "amount": 10 } POST - Criação POST /orders
94. { "product":"beer", "amount": 10 } POST - Criação POST /orders { "id":"12313132131312" } Response
95. { "product":"beer", "amount": 10 } POST - Criação POST /orders { "id":"12313132131312" } Response Identificador do recurso recém criado
96. GET /orders GET - Resgate
97. GET /orders no body GET - Resgate
98. [ { "id":"12313132131312" "product": "beer", "amount": 15, "sentEmail" : false, "taxed": true } ] GET /orders no body GET - Resgate Response
99. [ { "id":"12313132131312" "product": "beer", "amount": 15, "sentEmail" : false, "taxed": true } ] GET /orders no body GET - Resgate Response
100. GET /orders/010101 no body GET - Resgate
101. GET /orders/010101 no body GET - Resgate Identificador do recurso recém criado
102. { "product": "beer", "amount": 15, "sentEmail": false, "taxed": true } GET /orders/010101 no body GET - Resgate Response Identificador do recurso recém criado
103. PUT /orders/010101 PUT - Atualização completa
104. { "product": "beer", "amount": 15, "sentEmail": false, "taxed": true } PUT /orders/010101 PUT - Atualização completa
105. PATCH /orders/010101 PATCH - Atualização parcial
106. { "status": "PAID" } PATCH /orders/010101 PATCH - Atualização parcial
107. DELETE DELETE /orders/010101
108. • URI • Recursos • Operações • Versionamento • Media Types • Status & Erros Code • Filtro e Paginações • Segurança (Inicial) 8 Padrões
109. Versionamento
110. • Todo software evolui • Garantir Retrocompatibilidade Versionamento
111. https://localhost:8080/restfulservice/v1/orders/{id}
112. https://localhost:8080/restfulservice/v1/orders/{id} Protocolo host port serviço versão recurso parâmetro
113. https://localhost:8080/restfulservice/v1/orders/{id} versão
114. GET /v1/orders/12345
115. GET /v1/orders/12345 { "id":"12313132131312" "product": "beer", "amount": 15, "sentEmail": false, "taxed": true }
116. GET /v1/orders/12345 • Payload { "id":"12313132131312" "product": "beer", "amount": 15, "sentEmail": false, "taxed": true }
117. GET /v1/orders/12345 • Payload • Contrato { "id":"12313132131312" "product": "beer", "amount": 15, "sentEmail": false, "taxed": true }
118. GET /v1/orders/12345 { "id":"12313132131312" "product": { "id":"12313132131312", "name":"beer" }. . . }
119. GET /v1/orders/12345 { "id":"12313132131312" "product": { "id":"12313132131312", "name":"beer" }. . . }
120. GET /v1/orders/{id} cliente 1 cliente 2 order-api GET /orders/1234 GET /orders/4455
121. GET /v1/orders/{id} cliente 1 cliente 2 order-api GET /orders/1234 GET /orders/4455
122. GET /v1/orders/{id} cliente 1 cliente 2 order-api GET /orders/1234 GET /orders/4455
123. GET /v1/orders/{id} cliente 1 cliente 2 order-api GET /orders/1234 GET /orders/4455
124. { "id":"12313132131312" "product": "beer", "amount": 15, "sentEmail": false, "taxed": true } GET /v1/orders/{id}
125. GET /v2/orders/{id} { "id":"12313132131312" "product": { "id":"12313132131312", "name":"beer" }. . . }
126. Mas esse tal de Contrato ?
127. Mas esse tal de Contrato ? { "id":"12313132131312" "product": { "id":"12313132131312", "name":"beer" }. . . } { "id":"12313132131312" "product": "beer", "amount": 15, "sentEmail": false, "taxed": true } V2 V1
128. OpenAPI • Especificação de como devemos documentar nossos contratos
129. OpenAPI
130. OpenAPI
131. OpenAPI
132. Media Type
133. Formatos Padronizados • application/json • application/xml Media Type Request • Accept: application/json Response • Content-type: application/json
134. Status & Error Code
135. • 100 - Informação • 200 - Resultado OK • 300 - Redirecionamento • 400 - Erro no Client • 500 - Erro no Server Status & Error Code
136. Status & Error Code
137. Status & Error Code
138. POST - Criação POST /orders
139. { "product":"beer", "amount": 10 } POST - Criação POST /orders
140. { "product":"beer", "amount": 10 } POST - Criação POST /orders { "id":"12313132131312" } Status code - 201 - Created
141. { "product":"beer", "amount": 10 } POST - Criação POST /orders
142. { "product":"beer", "amount": 10 } POST - Criação POST /orders { "errorCode":"GBDD19" } Status code - 500 - Server Error
143. { "product":"beer", "amount": "10" } POST - Criação POST /orders
144. { "product":"beer", "amount": "10" } POST - Criação POST /orders { "error":"amount invalid" } Status code - 400 - Bad Request
145. [ { "product": "beer", "amount": 15, "sentEmail": false, "taxed": true } ] GET /orders no body GET - Resgate Status code - 200 - Ok
146. [] GET /orders no body GET - Resgate Status code - 204 - No Content
147. GET /orders/010101 no body GET - Resgate { "product": "beer", "amount": 15, "sentEmail": false, "taxed": true } Status code - 200 - Ok
148. GET /orders/010102 no body GET - Resgate Status code - 404 - Not Found no body
149. Filtros
150. Dependendo do recurso é inviável retornar todos os itens no GET /orders Filtros
151. Dependendo do recurso é inviável retornar todos os itens no GET /orders Mas precisamos garantir a flexibilidade Filtros
152. Filtros [ { "product": "beer", "amount": 15, "sentEmail": false, "taxed": true }, { "product": "sanduba", "amount": 20, "sentEmail": false, "taxed": false } ]
153. Escolhemos os atributos que fazem sentido termos como filtro Filtros [ { "product": "beer", "amount": 15, "sentEmail": false, "taxed": true }, { "product": "sanduba", "amount": 20, "sentEmail": false, "taxed": false } ]
154. Escolhemos os atributos que fazem sentido termos como filtro Filtros [ { "product": "beer", "amount": 15, "sentEmail": false, "taxed": true }, { "product": "sanduba", "amount": 20, "sentEmail": false, "taxed": false } ]
155. GET /orders?taxed=true Filtros
156. GET /orders?taxed=true Filtros
157. GET /orders?taxed=true Filtros [ { "product": "beer", "amount": 15, "sentEmail": false, "taxed": true } ]
158. Definir um limite de dados retornados em nossa API é importante para garantirmos nosso tempo de resposta Paginação
159. GET /orders?page=1&page_size=1 Paginação [ { "product": "beer", "amount": 15, "sentEmail": false, "taxed": true } ]
160. Segurança
161. Básico • Sempre usar https • Nunca expor dados sensíveis na URL Segurança
162. Básico • Sempre usar https • Nunca expor dados sensíveis na URL Segurança Avançado • Basic Authorization: Basic <credential> • JWT | Authorization: Bearer <credential> • OAuth 2.0
163. GET /orders/1 Segurança GET /orders/012012012012 sequencial UUID
164. POST /calculate Ações Status code - 200 - Ok
165. fim Mattheus Cassundé cassunde.com.br Mattheus Cassundé Software Engineer @cassunde