The document discusses various API design anti-patterns, highlighting issues related to operational efficiency, user experience, and performance within microservice architectures. It emphasizes the importance of using appropriate HTTP methods, implementing webhooks, and structuring APIs effectively to improve data retrieval and user interaction. The author advocates for thoughtful design processes that consider use cases and logging for better operational insights.

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
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!