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.

1. Construindo APIs
RESTful com Spring

2. E aí véi!
Mateus Malaquias
Senior Software Developer
@mmalaquiasdev
http://bit.ly/malaquiaslinkedin

3. ▣ https://soujava.org.br
▣ https://twitter.com/soujava
▣ http://bit.ly/soujava-youtube

4. ▣ https://medium.com/collabcode
▣ https://twitter.com/collabcodetech
▣ https://www.facebook.com/collabcode

5. AGENDA
▣ URI
▣ Recursos
▣ Verbos HTTP
▣ Status Code
▣ Media Types
▣ Filtros e paginação
▣ Caching
▣ Versionamento
▣ Documentação
▣ Modelo de Maturidade de
Richardson (HATEOAS)

6. 1.
Um breve
contexto
Antes de qualquer
coisa precisamos
entenderalgumas
coisas…

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.

8. REST vs SOAP

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.

12. ‘’
Qual a diferença entre MVC action
based e component based?
Leia mais:
http://bit.ly/actionoucomponent

14. 2.
URI
Uniform Resource
Identifier

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

18. 3.
Recursos
Utilize substantivos,
evite verbos e não use
nome de funções

19. Coleção e elemento
…/vagas/criarCurriculo
…/vagas/getTodosCurriculos

21. Coleção e elemento
…/vagas/curriculos
…/vagas/curriculos/29

22. Sub-elementos
…/vagas/curriculos/29/certificados/2

23. ‘’
▣ Ao usar sub-elementos tenha
um cuidado a mais para para
evitar encadeamentos, pois
pode de dificultar a evolução da
API.

24. Encadeamento de sub-elementos
…/29/certificados/2/servidores
…/29/certificados/2/servidores/892

25. 4.
Verbos HTTP
O mínimo que você
precisa saber sobre:
GET, POST, PUT,
DELETE...PATCH e
OPTIONS.

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

33. DEMO

34. 5.
Status Code 200, 400 ou 500?

35. As familias mais utilizadas
4xx2xx 5xx
Tá tudo bem O cliente fez
algo que eu
não entendi
Ops! Quebrei

36. As vezes você se depara com isso...
POST …/usuarios
HTTP/1.1 200 OK
{
"codigo":"-99",
"msg":"Error interno"
}

38. A familia 200
2xx
Tá tudo bem

39. Status: 200 OK
GET …/usuarios
[
{
"id":"421524",
"nome":"Mateus",
"senha":"123456",
"email":"mateusmalaquiasdev@outlook.com"
},
...
]

40. Status: 201 Created
OU
{
"telefone":"11999999999"
}
HTTP/1.1 201 Created
Location: …/usuarios/421524/telefones
POST …/usuarios/421524/telefones

41. Status: 202 Accepted
{
"href":"/usuarios/421524/documentos/2130040"
}
POST …/usuarios/421524/documentos

42. A familia 400
4xx
O cliente fez
algo que eu
não entendi

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

45. Os mais utilizados
401 Unauthorized
403 Forbidden
404 Not Found
429 Too Many Requests

46. A familia 500
5xx
Ops! Quebrei

47. Status: 500 Internal Server Error
POST …/usuarios
{
"status": 500,
"msg": "Ops! Aconteceu um erro um interno“
}

48. ‘’
▣ Lista completa de status
https://httpstatuses.com/

49. DEMO

50. 6.
Media Types
Basicamente
trabalhamos
com um tipo

51. JSON vs XML

52. E no Header como é que fica?
OPTIONS …/usuarios
HTTP/1.1 200 OK
Server: Apache/2.0.61 (Unix)
Accept: application/json
Vary: Accept-Encoding, Origin
Content-Encoding: gzip
Content-Length: 0
Keep-Alive: timeout=2, max=100
Connection: Keep-Alive
Content-Type: application/json

53. 7.
Filtros e paginação Tudo tem um limite

54. Filtros com escopo
GET …/usuarios?status=ativos&nome=Ma

55. Filtros com respostas parciais
GET …/usuarios/1?fields=nome,email

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

59. Paginação das suas coleções
GET …/usuarios?page=10&size=50

61. Quem controla o limit é a API
GET …/usuarios?page=5&size=500

62. DEMO

63. 8.
Caching
Evite uma super
lotação

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?

67. DEMO

68. 9.
Versionamento
Eu prefiro ser essa
metamorfose
ambulante

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)

71. Quando uma versão muda?
https://api.twitter.com/1.2/search

72. Quando uma versão muda?
https://api.twitter.com/2.0/search

73. 10.
Documentação
O guia dos
mochileiros das APIs

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

76. DEMO

77. 11.
Modelo de
Maturidade de
Richardson
(HATEOAS)
Em busca da glória do
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/

84. OBRIGADO
POR NÃO
DORMIR!
Perguntas?
@mmalaquiasdev
mateusmalaquiasdev@outlook.com