O documento discute os principais conceitos de APIs RESTful, incluindo: (1) recursos identificados por URIs e manipulados por verbos HTTP; (2) cache, autenticação e conteúdo negociado; (3) versionamento, erros e outros aspectos importantes de APIs REST.

1. REST
The right way

2. Quem sou?
Luís Santos - luis@luissantos.pt
Developer @ SAPO - Portugal Telecom

3. Rest: O que é?

4. Rest: O que é?
●
●
●
●
Representational state transfer
Arquitectura
Baseada em HTTP
Principios
○ Client-Server
○ Stateless
○ Cacheable
○ Layered System

5. Rest: Porquê?

6. Multiplataforma
●
Servidores
○
●
Todos os sistemas operativos e plataformas
Clientes
○
Todas as plataformas (incluindo p. moveis)

7. Segurança
● Confidencialidade dos dados
○ SSL
■ Destribuição de certificados
● Autenticação com certificados de cliente

8. Escalabilidade
● Escalabilidade horizontal
○ Proxys
○ Cache
○ Load Balancer

9. Recursos

10. Recursos
Elementos de informação ou “registos” que podem usados através do seu URI (uniform resource
identifier).
Exemplos:
/api/books/
/api/books/9780199535569/
/api/books/9780199535569/authors
/api/authors/
/api/authors/123/

11. Verbos HTTP
GET, POST, PUT, DELETE, HEAD,
OPTIONS, PATCH(?)

12. Verbos: GET
Obter informação sobre um recurso. Este verbo não afecta o estado do
recurso.
Verbo
endpoint
descrição
GET
/api/books/
Lista todos os livros
GET
/api/books/?limit=2&offset=10
Lista livros usando paginação
GET
/api/books/author=John doe
Pesquisa livros pelo nome do autor
GET
/api/books/9780199535569/
Detalhes de um livro

13. Verbos: GET
Pedido
Resposta
{
"total": 20,
GET /api/books/?limit=2&offset=10
"items": [
{
"isbn": "9780199535569",
"name": "Pride and Prejudice"
},
{
"isbn": "9780199535569",
"name": "Pride and Prejudice"
}
]
}

14. Verbos: GET
Pedido
Resposta
Http 1.1 200 OK
GET /api/books/9780199535569/
{
"isbn" : "9780199535569",
"name" : "Pride and Prejudice",
"publication_date" : "2009”
}

15. Verbos: POST
Cria um novo recurso.
Verbo
POST
endpoint
/api/books/
descrição
Adiciona um novo livro

16. Verbos: POST
Pedido
Resposta
POST /api/books/
Http 1.1 201 Created
{
{
"name" : "My Book"
"isbn" : "9999999999991",
}
"name" : "My Book"
}

17. Verbos: PUT
Modifica ou adiciona um recurso expecifico.
Verbo
PUT
endpoint
/api/books/9780199535569/
descrição
Altera ou adiciona o recurso

18. Verbos: PUT
Pedido
Resposta
PUT /api/books/9999999999991/
{
{
"name" : "My Book 2"
"name" : "My Book 2"
}
}

19. Verbos: DELETE
Apaga um recurso.
Verbo
DELETE
endpoint
/api/books/9780199535569/
descrição
Apaga o recurso

20. Verbos: DELETE
Pedido
Resposta
DELETE /api/books/9999999999991/
Status 200

21. Verbos: HEAD
Verifica se um recurso existe.
Verbo
HEAD
endpoint
/api/books/9780199535569/
descrição
Verifica se um recurso existe

22. Verbos: HEAD
Pedido
Resposta
HEAD /api/books/9780199535569/
Status 200

23. Verbos: PATCH
Modifica parcialmente um recurso.
http://www.rfc-editor.org/info/rfc5789 (Status: PROPOSED STANDARD)
Verbo
PATCH
endpoint
/api/books/9780199535569/
descrição
Altera apenas algumas propriedades do
recurso.

24. Verbos: PATCH
Pedido
Resposta
PATCH /api/books/9780199535569/
{
{
"name" : "My Book 2",
"publication_date" : "2008”
}
"publication_date" : "2008”
}

25. Verbos: OPTIONS
Obtem metada sobre o recurso.

26. HTTP Status
Code
1xx, 2xx , 3xx, 4xx, 5xx

27. Http Status Code

28. Http Status Code
● 2xx - Sucesso
● 4xx - Erro (Client side)
● 5xx - Erro (Server side)

29. Http Status Code : Exemplos
●
●
●
●
●
●
200 Ok
400 Bad Request
404 Not Found
401 Unauthorized
403 Forbidden
500 Internal Server Error

30. Error Handling

31. Error Handling

32. Error codes
●
●
●
●
●
Usar sempre um código HTTP adequado
Códigos de erro categorizados
Mensagem de erro
Link para a documentação
Identificador unico do pedido
○ Debug

33. Error codes
Certo
{
Errado
{
"error": 1345
"message" : "Invalid ISBN code"
"details" :"https://books.com/doc/errors/1345"
“id” : 12398231987312
}
"error": 1345
}

34. Cache

35. Cache
● Suporte para cache no protocolo
● Server Cache vs Client Cache
● Cache Headers
○ Cache-Control
○ Last-Modified
○ Etag

36. Cache: Client Cache (Cache-Control)

37. Cache: Client Cache (Last-Modified)

38. Cache: Client Cache (Etag)

39. Cache: Server Cache

40. Cache: Cache-Control
●
●
●
Cache-control: public
○ means the cached version can be saved by proxies and other
intermediate servers, where everyone can see it.
Cache-control: private
○ means the file is different for different users (such as their personal
homepage). The user’s private browser can cache it, but not public
proxies.
Cache-control: no-cache
○ means the file should not be cached. This is useful for things like
search results where the URL appears the same but the content may
change.

41. Autenticação

42. Autenticação
1.
●
●
2.
Utilização do header de autenticação. (Authorization)
Basic Authentication
○ Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Custom Authentication Scheme (Amazon AWS)
○ Authorization: AWS AKIAIOSFODNN7EXAMPLE:frJIUN8DYpKDtOLCwo//yllqDzg=
Utilização de certificado de cliente (SSL)

43. Content Type

44. Content Type
● JSON
○ Performance
○ Simplicidade
○ Dynamic Language (PHP,JS)
● XML
○ More tools
○ More features
○ Static language (Java,C#)

45. Content Type
Certo
GET /api/books/9780199535569
Accept: application/json
Errado
GET /api/books/9780199535569.json
GET /api/books/9780199535569.xml
GET /api/books/9780199535569
Accept: application/xml
GET /api/books/9780199535569
Accept: application/epub+zip
GET /api/books/9780199535569?type=json

46. Versionamento

47. Versionamento
Certo
GET /api/v10/books/9780199535569
Errado
GET /api/books/9780199535569?v=10
GET /api/books/9780199535569
X-API-Version : 10

48. Concorrência

49. Concorrência
Problema:
2 clientes tentam modificar o recurso simultaneamente.
Como garantir que as alterações não se sobrepõem?
Solução:
Etag

50. Concorrência

51. WADL
Web Application Description Language

52. WADL
● “The Web Application Description Language
(WADL) is a machine-readable XML
description of HTTP-based web applications
(typically REST web services).” - Wikipedia
● Semelhante ao WSDL

53. WADL
<application xmlns="http://wadl.dev.java.net/2009/02">
<resources base="https://books.com/api">
<resource path="books">
<method name="GET">
<request>
<param name="limit" required="false" default="30" style="query"/>
<param name="offset" required="false" default="0" style="query"/>
</request>
</method>
<resource path="{isbn}">
<param required="true" style="template" name="isbn"/>
<method name="GET"/>
<method name="DELETE"/>
</resource>
</resource>
</resources>
</application>

54. Outros
● Compressão “out of the box”
○ Gzip

55. Hypermedia API

57. FIM