If you've built an API before, you probably have some strong opinions about some of the things I've laid out here.

One thing that makes me feel a little heated, myself, is that this API is not particularly discoverable. For example, just looking at an API response, I can't tell what type of resource a relationship is. I can't even tell that a to-many relationship exists!

In the hypothetical, academically-perfect RESTful API, we'd have full HATEOAS. This annoying acronym means "Hypertext As The Engine Of Application State." It means that each resource you receive gives you not only its own information, but also instructions about what else you can do and where else you can go from here. If you've ever learned how to navigate a website by clicking its links, you've benefited from HATEOAS.

It's a beautiful concept, and many hypermedia nerds (like myself) dream of fully assumption-free APIs, where a client merely needs a single URL to serve as an entrypoint and can then discover everything else from there, without documentation. Entire user interfaces could be generated without writing a single line of application-specific code! The dream!

In reality, this is basically never possible. More importantly, it's basically never useful. Being able to write a couple cURL commands to get some data from an API without having to look at its documentation is great, and it's something to strive for—not just for easy curls, but because everything else gets easier too. But also, documentation is great, and it's necessary. If you specify 100% of your routes and their possible interactions in your docs, there's really no need for your API to be fully discoverable. Instead, focus on the ergonomics of reading and writing the data that you do choose to expose.