API Design

Nov 18, 2016

Designing Good (REST) APIs

Let’s start this off with a brief question, what is a good API? What is a bad API? Having the priviledge of working with both, there are signs:

  • Is it API versioned? Does it have a latest endpoint set? If no, prepare for pain.

  • Is the API payload versioned?

  • Is it as small as possible?

  • Does it make sense? Example of not making sense: ID path variable in the url and also in the payload.

  • Does it have system-wide side effects? Does calling the endpoint trigger a message into a messaging system that causes other asynchronous things to happen? That is completely cool but make sure you can trace messages going thru your system or you’re going to have a bad time.

  • Do you have behavior tests and unit tests around your API?

  • Do your consumers have PACT tests?