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/

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