Apidays New York 2024 - Build a terrible API for people you hate by Jim Bennett, liblab

Build a terrible API for people you hate
Jim Bennett, Principal Developer Advocate at liblab

Apidays New York 2024: The API Economy in the AI Era (April 30 & May 1, 2024)

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/

Transcript

1. Build A Terrible API For People You Hate Jim Bennett Principal developer advocate liblab
3. Who has worked with someone they hated? Is it time for malicious compliance?
4. We need an API for a ticketing system But we hate the person we need to build it for…
5. We could be nice, Let’s build a terrible API! but let’s be mean instead…
6. 6 steps to build a terrible API for people you hate The best docs are…
7. Step 1 The best API docs are… screenshots embedded in an Excel spreadsheet! And are wrong!
8. Nice Jim would… provide an OpenAPI spec! Industry standard and can be used to generate decent documentation and client SDKs.
9. Step 2 GET all the things!
10. How do we create a new user? We GET a new user obviously!
11. HTTP request methods GET POST PUT PATCH DELETE POST PUT PATCH DELETE
12. Nice Jim would… support request methods correctly, using POST to create a new user.
13. Step 3 Naming things is hard so let’s not bother doing it well.
14. We need lots of ticket endpoints /add_ticket - add a ticket /uticket - update a ticket /allTickets - get all tickets /tikcet - get one ticket. Was spelled wrong, so we can’t change it now!
15. Nice Jim would… support request methods correctly, so we can have just one endpoint: /ticket /ticket/{id}
16. Step 4 Request bodies are better than path or query parameters.
17. To get a ticket, put the ID in the request body Make a request to /tikcet Pass the ticket ID in the body: { “ticket_id”: 1 }
18. To update a ticket, put the ID in the request body Make a request to /uticket Pass the ticket ID in the body with the rest of the fields to update: { “ticket_id”: 1 “status”: “done” }
19. To search for a ticket, put the search criteria in the request body Make a request to /search_tickets Pass the search criteria in the
body: { “status”: “open” }
20. Nice Jim would… use path parameters and query parameters instead of sending identifiers in a request body
21. Step 5 Non-200 status codes are bad and make client code throw exceptions! Always return 200!
22. Return 200, and put the error in the response! Status: 200 OK { “status”: 404, “message”: “Ticket not found” }
23. HTTP status codes mean things 1xx - hold please 2xx - here you go! 3xx - go away 4xx - you mucked up 5xx - I mucked up
24. HTTP status codes mean things 200 - OK! 400 - bad request 401 - unauthorized 404 - not found 418 - I’m a teapot Status: 200 OK Don’t care! Always return 200!
25. Nice Jim would… return the appropriate status code for an error, and include more details in an error response body.
26. Step 6 Atomic updates? Nah!
27. Creating a user will insert into 2 tables 2 tables - user and user_details Record inserted into user table Data is missing from the request, so an insert into the user_details table fails API returns an error
28. Creating a user will insert into 2 tables User retries - duplicate in the user table
29. Nice Jim would… ensure all updates are atomic - if the API call fails the system is in the same state as before the call.
30. What if we don’t hate them? Provide an OpenAPI spec Use correct request methods Have good naming Use path parameters Return proper status codes Always do atomic updates
31. Hi, I’m Jim He/Him Principal developer advocate liblab @jimbobbennett linktr.ee/jimbobbennett