Stop saying “Endpoints”
To design a hypermedia REST API that delights its users, drop the endpoint.
There doesn’t seem to be any other type of API being created today, they’re all RESTful. Except they’re usually far from it, very rarely are they hypertext driven.
But making them hypertext driven like a website, is made tougher all the while you’re using the term “endpoint” when you’re talking about resources and URLs.
Talking about an endpoint makes us think in terms of implementation, invoking some code at the end, and not in terms of experiencing the API from the user’s point of view.
Consider a website. It’s really just a REST API between a human/browser and a machine. When designing a website the team doesn’t talk about https://www.beatport.com/checkout/thanks as an endpoint, no, it’s just the thanks page with some useful links.
The web designers at Beatport thought about the journey the user is on, chose a friendly URL then came up with an appropriate page, a HTML resource representation, that makes for the best experience for a human, affording an onward journey via a new set of hyperlinks.
When designing APIs, if your team talks in endpoints then you’re tempted to argue, why do I need a new endpoint for thanks? Or, why does a client need to traverse through all these other endpoints when I could just build a big, final endpoint with everything on it that my client needs?
If we thought like that with websites, we’d be back to those horrible 90s portal homepages with a million links and 5 forms on it.
The scalability of the web is due to its statelessness; of course there’s state in my cart but my intentions are communicated statelessly via URLs and verbs.
Imagine I intend to apply for an insurance quote.
What should the URL be for this course of action? Does it even matter? Is it important that the URL conveys information about what it does or should that information be in the markup or JSON around it?
Which other resources should link-to this action? What’s the goal or journey for a client? Does the application need to collect further information and do some questions depend on the answers to others? And can it do all that using only information conveyed in a single URL?
The Garden of Forking Paths
It helps to understand that hypertext works because it guides clients along a good path to arrive at a destination, some task such as transferring money or signing up to be notified of some home automation action, and that URLs don’t much matter and endpoints aren't even a thing.
Talking of which, here’s a link to take you down a new path.
Websites and RESTful APIs are nothing but a builder pattern
A Dynamic Hypermedia Client
So I wrote a hypermedia client that demonstrates the ideas above. This one is useful as it demonstrates a hypertext API, and they’re so rare that I don’t think many people have ever seen one to really see the light.
