Thoroughly document your API. Please. That is all.
Thorough API documentation allows consumers of your API to more easily generate clients for, and test against, your service.
REST API Client generation
Recently, while working on a Go project at work, I needed a REST API client for an external API. Having written a couple of API clients in the past, I wasn’t necessarily looking forward to the repetitiveness that came with implementing endpoint after endpoint after endpoint after… so I took some time to looking for anything that would get me off the hook.
I pretty quickly found gnostic, a tool developed by Google that converts OpenAPI documents to Google’s attempt at standardizing structured data, Protocol Buffers. Luckily, there is also a pretty stable plugin for gnostic which uses the Protocol buffers definition to generate Go servers and clients gnostic-go-generator!
This seems great! The external API I was writing a client for had OpenAPI documentation, conveniently hosted for us to try out.
With OpenAPI docs in hand, I got gnostic up and running relatively easily, Go plugin included. I didn’t need the generated server, but thankfully that was easy to ignore.
Swiss cheese
Holes everywhere! The client generated by gnostic had pieces missing everywhere, making it all essentially useless. But gnostic and the Go generator plugin did their job well enough, so what happened?
Taking a second look at the API documentation that we were provided, I realized just how incomplete it was. Example response data was completely absent, and the same three response codes were returned for all endpoints, regardless of the action being performed. This meant that none of the endpoints implemented by gnostic returned anything, and none of the response data was modeled.
By taking the time to thoroughly document your APIs, you are passing on time savings to the consumers of your service. Even if someone is hand writing a client for your service instead of generating one, having a complete picture of what they are implementing goes a long way towards making consumers of your service happy.