Este documento apresenta uma introdução sobre como construir APIs RESTful com Spring. A agenda inclui tópicos como URI, recursos, verbos HTTP, códigos de status, tipos de mídia, filtros e paginação, cache, versionamento, documentação e o modelo de maturidade de Richardson (HATEOAS). O documento fornece exemplos e explicações concisas sobre cada um desses conceitos importantes para o desenvolvimento de APIs RESTful.
7. O termo é REST ou RESTful?
▣ Rest é um estilo arquitetural
que foi criado por Roy
Fielding.
▣ RESTful é o design dos
contratos de APIs que
respeita os conceitos REST.
10. Spring MVC
▣ É um action Web MVC framework que é suportado pelo Spring
Boot e os convencionais servidores Java.
▣ É muito utilizado para implementação de aplicações Web ou
para REST APIs.
▣ Ele possui uma implementação do pattern FrontController que
basicamente é responsável por receber todas as requisições,
delega-las para os respectivos controllers e retornar a devida
resposta.
11.
12. ‘’
Qual a diferença entre MVC action
based e component based?
Leia mais:
http://bit.ly/actionoucomponent
15. Estrutura básica [ 1 ]
https://api.twitter.com/1.1/search
Seu domínio
HTTPS
ou
HTTP
Recursos e
Parâmetros
Versão da API
(opcional)
16. Estrutura básica [ 2 ]
https://api.fcamara.com.br/vagas/curriculos
Seu domínio
HTTPS
ou
HTTP
Recursos e
Parâmetros
Nome da API
(opcional)
17. ‘’
▣ Identificador de Recursos Universal,
como diz o próprio nome, é o
identificador do recurso. Pode ser
uma imagem, uma página, etc, pois
tudo o que está disponível na
internet precisa de um identificador
único para que não seja confundido.
▣ Leia mais: http://bit.ly/urlvsuri
25. 4.
Verbos HTTP
O mínimo que você
precisa saber sobre:
GET, POST, PUT,
DELETE...PATCH e
OPTIONS.
26.
27. GET: Um método de consulta
▣ Cacheável
GET …/usuarios
GET …/usuarios/301
28. POST: Um método para criação
▣ Não é Cacheável
▣ Informações são transitadas no corpo da requisição
POST …/usuarios
{
"username": "Malaquias",
"password": "123456",
"city": "Salvador",
"interests": "Java"
}
29. PUT: Um método para atualização
▣ Não é Cacheável
▣ Informações são transitadas no corpo da requisição
PUT …/usuarios/301
{
"username": "Malaquias",
"password": "123456",
"city": “São Paulo",
"interests": "Java"
}
30. DELETE: Um método para remoção
▣ Não é Cacheável
DELETE …/usuarios
DELETE …/usuarios/301
31. PATCH: Um método para atualização parcial
▣ Não é Cacheável
PATCH …/usuarios/301
{
"password": “ab21ac2",
}
32. OPTIONS: Quais verbos posso usar?
OPTIONS …/usuariosHTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD, POST
Cache-Control: max-age=604800
Date: Thu, 13 Oct 2016 11:45:00 GMT
Expires: Thu, 20 Oct 2016 11:45:00 GMT
Server: EOS (lax004/2813)
x-ec-custom-error: 1
Content-Length: 0
43. Status: 400 Bad Request
POST …/usuarios
{
"status":400,
"msg":"Nome do usuário não pode ser nulo ou vazio",
"doc":"https://api.fcamara.com.br/erros/nome-usuario"
}
44. Status: 404 Not Found
GET …/usuarios/64721
{
"status":404,
"msg":“Usuário não foi encontrado",
"doc":"https://api.fcamara.com.br/erros/usuario-nao-existe"
}
58. ‘’
▣ Gosto de pensar no Graphql
como uma forma de
desenvolver uma API orientado
a tipos, pois tudo no Graphql se
resume a tipos e resolvers.
▣ Leia mais: http://bit.ly/2uU0eSb
65. Fazer caching é uma boa prática!
▣ Vamos evitar tráfego
▣ Diminuir a latência de rede
▣ Evitar que nossos servidores fiquem
sobrecarregados
66. Mas temos que ter cuidado com...
▣ O tempo que vamos invalidar o cache
▣ Se alguma ação vai invalidar o cache
▣ Faz clusters? Como sincronizar o cache?
69. As coisas mudam
Dificilmente uma API será completamente estável, mudanças são
sempre inevitáveis, então é importante para o seu negócio que
você consiga caminhar sem quebrar.
70. Voltamos a estrutura básica [ 1 ]
https://api.twitter.com/1.1/search
Versão da API
(opcional)
74. Uma boa documentação tem...
▣ Descrição, tutoriais de uso e exemplos
▣ Ela pode ou não ser interativa
▣ Está sempre atualizada
▣ Quando se tem muitas APIs, um catalogo é
uma opção interessante de se ter
75. Swagger
▣ Modelagem da API
▣ Geração de documentação (legível) da API
▣ Geração de códigos do Cliente e do Servidor, com suporte a
várias linguagens de programação
▣ No Java usamos anotações para gerar a documentação
O Swagger é um projeto composto por algumas ferramentas que
auxiliam o desenvolvedor de APIs REST
79. Nível 0 - POX
HTTP URI OPERAÇÃO
GET /getUsuarios/1 Retorna
POST /criarUsuarios Cria
POST /atualizarUsuarios/1 Atualiza
POST /deleteUsuarios/1 Deleta
É o nível mais baixo de uma API RESTful, aqui não se usa padrão
para praticamente nada.
80. Nível 1 – Recursos [ 1 ]
HTTP URI OPERAÇÃO
GET usuarios/1/buscar Retorna
POST usuarios/criar Cria
POST usuarios/1/atualizar Atualiza
POST usuarios/1/deletar Deleta
Se usa pelo menos os recursos como uma forma de modelar e
organizar APIs.
81. Nível 1 – Recursos [ 2 ]
HTTP URI OPERAÇÃO
GET usuarios/1 Retorna
POST usuarios Cria
PUT usuarios/1 Atualiza
DELETE usuarios/1 Deleta
Se usa pelo menos os recursos como uma forma de modelar e
organizar APIs.
82. Nível 2 – Verbos HTTP
HTTP URI OPERAÇÃO STATUS
GET usuarios/1 Retorna 200, 400, 500
POST usuarios Cria 200, 400, 500
PUT usuarios/1 Atualiza 200, 400, 500
DELETE usuarios/1 Deleta 200, 400, 500
Aqui já se utiliza os verbos HTTP e os STATUS code na execução
de uma operação.
83. Nível 2 – Hypermedia
Tem como elemento principal a representação hypermedia,
permitindo que um documento descreva seu estado atual, e o
seu relacionamento com outros elementos ou futuros estados.
Link de exemplo: https://pokeapi.co/