API Design

A keynote made for Papaya Ventures explaining the main points when developing an API.

Transcript

1. por que você deveria se importar? API design
2. Como enviar dados para a nuvem?
3. API Application Programming Interface Fácil de usar Rápida Leve JSON
4. Construindo uma API
5. Representational State Transfer REST
6. Arquitetura DISTRIBUÍDA
7. Representação de Entidades /posts/1.json /posts/1/comments.json /posts/1/likes.json
8. HTTP METHOD ACTION VERBO SUBSTANTIVO GET DELETE POST PUT /posts /posts /posts/1 /posts/1
9. USE Substantivos ao inves de verbos
10. verbos criam uma API prolixa GET /listarPosts.json POST /criarPost.json GET /visualizarPost.json?id=1
11. Se aproveite dos HTTP methods GET /posts.json POST /posts.json GET /posts/1.json PUT /posts/1.json DELETE /posts/1.json
12. Sempre plural, nunca singular
13. ENdpoints no plural são intuitivos GET /posts GET /posts/1 PUT /posts/1 POST /posts
14. Substantivos concretos, nunca abstratos
15. Endpoints devem ter significado GET /items GET /products GET /users GET /assets Ruim Bom
16. RELACIONE RECURSOS DE FORMA SIMPLES
17. Endpoints auto-explicativos Foto Likes POST /photos/1/likes Categoria Estabelecimentos GET /categories/restaurant/venues
18. Coloque a complexidade DEPOIS da “?”
19. filtros e buscas GET /posts?status=draft GET /posts/1/comments?user_id=1 GET /posts?q=something
20. Resultados devem ser paginados
21. Indiquem onde o resultado está GET /posts { “posts”: [ { “id”: 1, title: “Post #1” }, { “id”: 2, title: “Post #2” } ], “page”: 1, “total”: 10, “perPage”: 2 } GET /posts?page=2&perPage=1 { “posts”: [ { “id”: 3, title: “Post #3” }, ], “page”: 2, “total”: 10, “perPage”: 1 }
22. Retorne dados parcialmente
23. Reduza o payload GET /posts/1 { “post”: { “id”: 1, “title”: “Post #1”, “body”: “Post’s body”, “tags”: [“api”, “web”, “http”], “category”: { “name”: “Development” } } } GET /posts/1?fields=id,title { “post”: { “id”: 1, “title”: “Post #1” } }
24. Retorne erros com significado
25. Seja claro! POST /posts { “status”: 400, “message”: “O título não pode ficar em branco” }
26. Versione sua API
27. E mantenha ao menos 1 versão GET /v1/posts/1 GET /v2/posts/1 { “post”: { “id”: 1, “title”: “Post #1”, “content”: “Post’s body” } } } { “post”: { “id”: 1, “title”: “Post #1”, “body”: “Post’s body” } } }
28. Use um subdomínio
29. api.seuprojeto.com Escalabilidade independente Controle de cache e CDN independente Organização
30. Wrap up
31. APIs podem fazer a diferença durante o desenvolvimento Cuidado com o Design
32. A mesma API pode ser core de aplicativos iPhone, Android, Web e Desktop Colha os frutos
33. Outros aplicativos podem aumentar o valor do seu produto expandindo o seu uso Aumente seu evaluation
34. O caso “Instragram”
40. Obrigado :)