Operational API Design Anti-Patterns

Talk from Nordic APIs Platform Summit in Stockholm, Oct 2016

Transcript

1. Operational API Design Anti-Patterns Jason Harmon @jharmn @typeform
2. Head of APIs @Typeform • Leading microservice replatform • Leading developer focused initiatives Previous API experience: • PayPal/Braintree • uShip • Wayport / AT&T Jason Harmon • Old blogs at: ◦ APIUX.com ◦ Pragmaticapi.com
3. “API Design Anti-Patterns” talk from last year • https://www.youtube.com/watch?v=lotdj-ry8YA Design issues don’t always cause operational issues. Haven’t we already talked about this?
4. Usability issues Operational issues
5. HTTP GET instead of POST
6. Landing GET /landing 200 OK { “Token”: “abc123” } User Human
7. A Form User Human
8. Submit User Human
9. Submit User Human Click “Back” ? Submit needs to have a landing (to derive “response rate”) POST /submissions (+landing_id in body)
10. Issue: GET Caches + HTTP GET GET /landing Caching Proxy Or CDN Cached response X 200 OK { “Token”: “abc123” }
11. Landings: Better User Human POST /landing 200 OK { “Token”: “abc123” }
12. • Identification: Unexpected cached API calls from browser/proxy/etc • Solution: Use POST • Live already? ◦ Just add POST ◦ Add ?cache_buster=[random] to GET Summary: GET instead of POST
13. Polling APIs
14. Polling APIs Problem Identification: • Large dataset • Expensive queries • Frequently changing data • Lots of clients Client app Every 5 mins Thousands of forms
15. Solution: Webhooks Client app Register URL New data = POST Still needed for missing data
16. WHAT IF THIS IS ALREADY HAPPENING!!?! Client app Options: • Launch webhooks! • Caching (if possible) • Read-only DB replica • Cheaper query to check for new data before retrieval
17. Rigid Hierarchy
18. Microservices structure: Forms
19. Issue: Many calls Microservices
20. Form Structure + Backend-for-Frontend Microservices B F F AKA • Composition • Orchestration GraphQL is another potential option
21. • Problem: ◦ Client performance in UX ◦ N+1 calls (client calls for parent, then calls for related/child items) • Identification: ◦ Data lacking in main resource, usually for UX devs. • Easy to add in live scenarios Summary: Rigid resource structure
22. Generic Actions
23. AKA RPC Commonly used in controlled state transitions: POST /forms/:id/publish { “comment”: “It’s the right time” } What’s an “action”
24. Perform multiple actions with one endpoint POST /forms/:id/change-status { “action”: “publish”, “comment”: “My favorite version of this form” } Generic “action”
25. Product Owner - Any performance issues? Devs
26. Product owner: - So how many “publish” actions happened? Devs
27. TO THE LOGS!
28. Dear Product Owner. We need to build a new metrics system to answer that question. - Yours truly, dev team. PO
29. Product Owner’s reply:
30. Cheap visibility is a good thing
31. Generic Actions • Identification: ◦ POST /resource/:id/generic-name + {action: process} • Problem: “Protocol tunneling”: ◦ Lack of traceability, more work for metrics (vs cheaper HTTP logs method) • Solution: ◦ POST /resource/:id/action-name • Already live? ◦ ?action=name in optional query parameter
32. API Design Takeaways
33. Use cases first, then design.
34. Design can influence performance.
35. Structure is good, but be prepared to blur the lines.
36. Design can put out fires.
37. Don’t forget the logs.
38. That’s it!