Este documento resume os principais pontos sobre APIs RESTful. Em 3 frases:
RESTful APIs devem usar recursos HTTP como URIs e verbos HTTP para representar entidades e operações. Elas devem ser stateless e usar códigos HTTP para indicar sucesso ou falha de requisições. Seguir padrões como JSON API Spec permite criar APIs mais robustas e com recursos como paginação entre outros.
2. Igor Santos who?
- Desenvolvedor PHP desde os 16 (~10 anos)
- Trabalho com APIs REST: ~4 anos
- Desenvolvedor React: ~2 ano
- Já mexi com Ruby, mas...
- Já brinquei com C e Python mas…
- Já me diverti com Ember mas…
Atualmente, sou Freelancer remoto Full-stack na
Join the network! Talk to me :D
8. #0: O pântano do POX*
✓ Comunicação sobre o HTTP
✗ HTTP = protocolo facilitador de rede, somente
✗ Verbos HTTP? GETPOST all the things!
*POX: Plain Old XML
10. #0: O pântano do POX* *POX: Plain Old XML
POST /api/
<listEvents date="2016-10-22"/>
----------------------------------------
HTTP/1.1 200 OK
<eventsList>
<event id="10">
<dates begin="2016-10-22">
<topics>
<topic>HTTP</topic>
<topic>REST</topic>
</topics>
[...]
11. #0: O pântano do POJ* *POJ: Pure and Old JSON
POST /api/?method=events.list
{ date: "2015-10-22" }
----------------------------------------
HTTP/1.1 200 OK
[
{
"id": 10,
"start": "2015-10-22",
"topics": [ "PHP", "REST" ],
"speakers": [
{
...
12. #1: Resources!
✓ Comunicação sobre o HTTP
✓ URIs indicam o recurso desejado
✓ Recursos HTTP simplificados, para dividir os requests
✗ Verbos HTTP? GETPOST all the things!
AKA entidades
15. #2: Eu chamo API, tu chamas API...
✓ Comunicação sobre o HTTP
✓ URIs indicam o recurso desejado
✓ Recursos HTTP dividem os requests
✓ Verbos HTTP dividem as operações
16. #2: Eu chamo API, tu chamas API...
Subníveis de uso dos Verbos HTTP
GET POST PUT DELETE
Básico Consultas
Criação
Edição
Remoção
X X
POST /clientes/buscar
GET /clientes
17. #2: Eu chamo API, tu chamas API...
Subníveis de uso dos Verbos HTTP
GET POST PUT DELETE
Básico Consultas
Criação
Edição
Remoção
X X
Quase lá Consultas
Criação
Edição
X Remoção
POST /clientes/apagar/2
DELETE /clientes/2
18. #2: Eu chamo API, tu chamas API...
Subníveis de uso dos Verbos HTTP
GET POST PUT DELETE
Básico Consultas
Criação
Edição
Remoção
X X
Quase lá Consultas
Criação
Edição
X Remoção
RESTful-ish Consultas Criação Edição Remoção
POST /clientes/edit/27
PUT /clientes/27
19. #2: Eu chamo API, tu chamas API...
Subníveis de uso dos Verbos HTTP
GET POST PUT DELETE PATCH
Básico Consultas
Criação
Edição
Remoção
X X X
Quase lá Consultas
Criação
Edição
X Remoção X
RESTful-ish Consultas Criação Edição Remoção X
RESTful-ish
bônus
Consultas Criação Edição Remoção
Edição
parcial
20. #2: Eu chamo API, tu chamas API...
Subníveis de uso dos Verbos HTTP
GET POST PUT DELETE PATCH
Básico Consultas
Criação
Edição
Remoção
X X X
Quase lá Consultas
Criação
Edição
X Remoção X
RESTful-ish Consultas Criação Edição Remoção X
RESTful-ish
bônus
Consultas Criação Edição Remoção
Edição
parcial
RESTful-ish
bônus plus
Além dos verbos certos,
usa os códigos HTTP e headers corretos
21. #2: Eu chamo API, tu chamas API...
GET /api/events?date=2016-10-22
----------------------------------------
HTTP/1.1 200 OK
[
{
"id": 10,
"start": "2016-10-22",
"topics": [ "HTTP", "REST" ],
"speakers": [
{
...
22. #2: Eu chamo API, tu chamas API...
POST /api/events
{ "start": "2016-10-22", ... }
----------------------------------------
HTTP/1.1 201 Created
[
{
"id": 10,
"start": "2016-10-22",
"topics": [ "HTTP", "REST" ],
"speakers": [
{
...
23. #2: Eu chamo API, tu chamas API...
DELETE /api/events/10
----------------------------------------
HTTP/1.1 204 No Content
24. #2.5: RESTful-ish
1. Códigos HTTP
- 200: OK, tá aqui o que você pediu
- 201: Criei, olha aqui o que eu fiz
- 204: Funcionou, mas não tenho mais nada pra te dizer
- 400: erro genérico do usuário
- 401: OW, quem é você?
- 403: OW, sei quem é você mas isso aqui não é pro teu bico
- 404: tem nada disso aqui não
- 405: verbo incorreto
- 406: não consigo gerar no formato que você quer
- 422: sabe nem escreve direito, mano
- 500: CORRÃO PARA AS MONTANHAS
- 501: não sei fazer isso não
29. #2.5: RESTful-ish
2. Stateful
- HTTP = stateless
- Stateless <> sessão
- API <3 sessão
- API + HTTP + sessão =
- HTTP Auth: autentica o usuário inicialmente
- HTTP Cookie - re-identifica o usuário, tornando
desnecessário re-autenticar a cada novo request
30. #2.5: RESTful-ish
2. Stateful
- HTTP = stateless
- Stateless <> sessão
- API <3 sessão
- API + HTTP + sessão =
- HTTP Cookie: inseguro no geral
- HTTP Auth: autentica o usuário inicialmente
- JSON Web Token: mantém o estado do lado do
cliente de modo seguro, livrando o servidor disso
31. #2.5: RESTful-ish
3. Formatos de resposta
- Método A: header HTTP Accept: text/xml
- Método B: extensão na URI: /events.json
- O correto: aceitar os dois métodos, e responder
em XML e JSON
- O mais comum: um dos dois métodos - ou nenhum,
e responder em JSON (mais leve de implementar e
interpretar)
32. #2.5: RESTful-ish
4. Versionamento da API
- Método A: incluído na URL
- Método B: header HTTP customizado
- Método C: incluído no header Accept
- O correto: nenhum
- O mais comum: na URL - mais fácil de implementar dos
dois lados e associa diretamente o método, o resource e
a resposta à disponibilidade destes na API
33. #2.5: RESTful-ish
4. Versionamento da API
- Método A: incluído na URL
- Método B: header HTTP customizado
- Método C: incluído no header Accept
- O correto: nenhum
- O mais comum: na URL - mais fácil de implementar dos
dois lados e associa diretamente o método, o resource e
a resposta à disponibilidade destes na API
38. #3: HATEOAS
JSON API Spec
- Uma especificação de verdade para APIs!
- Bem completa, complexa mas bem poderosa
- Dá pra fazer um monte de coisas com ela
- Muito legal <3
39. #3: HATEOAS
JSON API Spec
- Uma especificação de verdade para APIs!
- Bem completa, complexa mas bem poderosa
- Paginação e navegação entre recursos
- Requisição de recursos relacionados no mesmo payload
- Meta informações sobre o request
- Formato definido entre requests de uma única ou múltiplas
entradas, dados de identificação
e atributos, relacionamentos, etc
42. Library recomendada: Restler
Classes puras + ORM + Restler = API RESTful e documentada
- Curva de aprendizado ≅ 0
- Muito leve; configuração flexível e customizável
- Features baseadas nas próprias features do OO e PHPDoc (assim
como o REST é baseado no HTTP, ahá!), como validação,
documentação, rotas customizadas, códigos de retorno, etc
- Suporta Rate limiting e OAuth 2
- Suporta respostas em JSON, XML, YAML, Plist e Amf
- Documentação automática e muito boa (Swagger)
OUTDATED
43. Library recomendada: Restler
Classes puras + ORM + Restler = API RESTful e documentada
Documentação
Código
- Word
- User
Exemplo prático:
OUTDATED
44. Framework recomendado: Laravel/Lumen
Resources automatizados em Controllers + framework
- Frameworks simplificados, e componentizados
- Bem leve
- Configuração flexível e customizável
- ORM poderoso já embutido
- Diversas outras ferramentas integradas, como
queues, events, logs, encriptação, validação, etc
50. Learn more about the
opportunities, come talk to me :)
Do you speak English?
Do you feel you’re great at what you do?
Looking for good clients, great pay, awesome teams and freedom?
51. That’s all,
folks!
- Richardson’s API Maturity Model
- API versioning discussion
- HTTP Headers spec
- HTTP Verbs: Wikipedia / Spec
- JSON API spec
- Postman
- Toptal Engineering Blog
*.com/igorsantos07
*.com/igorsantos07
*.com/in/igorsantos07
Portfolio: freelancer.igorsantos.com.br
Apply: toptal.igorsantos.com.br
52. That’s all,
folks!
Peço desculpas por todas as piadas
e trocadilhos ruins usados nesta
palestra. Carlos Alberto de Nóbrega
não esteve envolvido com a
mesma.
*.com/igorsantos07
*.com/igorsantos07
*.com/in/igorsantos07
Portfolio: freelancer.igorsantos.com.br
Apply: toptal.igorsantos.com.br