rest - the right way
Post on 28-Jun-2015
386 Views
Preview:
TRANSCRIPT
RESTThe right way
Quem sou?
Luís Santos - luis@luissantos.ptDeveloper @ SAPO - Portugal Telecom
Rest: O que é?
Rest: O que é?● Representational state transfer● Arquitectura● Baseada em HTTP● Principios
○ Client-Server○ Stateless○ Cacheable○ Layered System
Rest: Porquê?
Multiplataforma● Servidores
○ Todos os sistemas operativos e plataformas
● Clientes
○ Todas as plataformas (incluindo p. moveis)
Segurança● Confidencialidade dos dados
○ SSL
■ Destribuição de certificados
● Autenticação com certificados de cliente
Escalabilidade
● Escalabilidade horizontal○ Proxys○ Cache○ Load Balancer
Recursos
RecursosElementos 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/
Verbos HTTPGET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH(?)
Verbos: GETObter 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
Verbos: GETPedido
GET /api/books/?limit=2&offset=10
Resposta{
"total": 20,
"items": [
{
"isbn": "9780199535569",
"name": "Pride and Prejudice"
},
{
"isbn": "9780199535569",
"name": "Pride and Prejudice"
}
]
}
Verbos: GETPedido
GET /api/books/9780199535569/
RespostaHttp 1.1 200 OK{ "isbn" : "9780199535569", "name" : "Pride and Prejudice", "publication_date" : "2009” }
Verbos: POSTCria um novo recurso.
Verbo endpoint descrição
POST /api/books/ Adiciona um novo livro
Verbos: POSTPedido
POST /api/books/
{ "name" : "My Book" }
Resposta
Http 1.1 201 Created{ "isbn" : "9999999999991", "name" : "My Book" }
Verbos: PUTModifica ou adiciona um recurso expecifico.
Verbo endpoint descrição
PUT /api/books/9780199535569/ Altera ou adiciona o recurso
Verbos: PUTPedido
PUT /api/books/9999999999991/
{ "name" : "My Book 2" }
Resposta
{ "name" : "My Book 2" }
Verbos: DELETEApaga um recurso.
Verbo endpoint descrição
DELETE /api/books/9780199535569/ Apaga o recurso
Verbos: DELETEPedido
DELETE /api/books/9999999999991/
Resposta
Status 200
Verbos: HEADVerifica se um recurso existe.
Verbo endpoint descrição
HEAD /api/books/9780199535569/ Verifica se um recurso existe
Verbos: HEADPedido
HEAD /api/books/9780199535569/
Resposta
Status 200
Verbos: PATCHModifica parcialmente um recurso. http://www.rfc-editor.org/info/rfc5789 (Status: PROPOSED STANDARD)
Verbo endpoint descrição
PATCH /api/books/9780199535569/ Altera apenas algumas propriedades do recurso.
Verbos: PATCHPedido
PATCH /api/books/9780199535569/
{ "publication_date" : "2008” }
Resposta
{ "name" : "My Book 2", "publication_date" : "2008”}
Verbos: OPTIONS
Obtem metada sobre o recurso.
HTTP Status Code1xx, 2xx , 3xx, 4xx, 5xx
Http Status Code
Http Status Code
● 2xx - Sucesso● 4xx - Erro (Client side)● 5xx - Erro (Server side)
Http Status Code : Exemplos
● 200 Ok● 400 Bad Request● 404 Not Found● 401 Unauthorized● 403 Forbidden● 500 Internal Server Error
Error Handling
Error Handling
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
Error codes
Certo{ "error": 1345 "message" : "Invalid ISBN code" "details" :"https://books.com/doc/errors/1345" “id” : 12398231987312}
Errado{ "error": 1345}
Cache
Cache
● Suporte para cache no protocolo● Server Cache vs Client Cache● Cache Headers
○ Cache-Control○ Last-Modified○ Etag
Cache: Client Cache (Cache-Control)
Cache: Client Cache (Last-Modified)
Cache: Client Cache (Etag)
Cache: Server Cache
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.
Autenticação
Autenticação1. Utilização do header de autenticação. (Authorization)
● Basic Authentication○ Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
● Custom Authentication Scheme (Amazon AWS)○ Authorization: AWS AKIAIOSFODNN7EXAMPLE:frJIUN8DYpKDtOLCwo//yllqDzg=
2. Utilização de certificado de cliente (SSL)
Content Type
Content Type
● JSON○ Performance○ Simplicidade○ Dynamic Language (PHP,JS)
● XML○ More tools○ More features○ Static language (Java,C#)
Content Type
Certo ErradoGET /api/books/9780199535569.json
GET /api/books/9780199535569.xml
GET /api/books/9780199535569?type=json
GET /api/books/9780199535569Accept: application/json
GET /api/books/9780199535569Accept: application/xml
GET /api/books/9780199535569Accept: application/epub+zip
Versionamento
Versionamento
Certo ErradoGET /api/v10/books/9780199535569 GET /api/books/9780199535569?v=10
GET /api/books/9780199535569X-API-Version : 10
Concorrência
Concorrência
Problema:2 clientes tentam modificar o recurso simultaneamente.Como garantir que as alterações não se sobrepõem?
Solução:Etag
Concorrência
WADLWeb Application Description Language
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
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>
Outros
● Compressão “out of the box”○ Gzip
Hypermedia API
FIM
top related