Stop saying “Endpoints”

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 an API.

A website is a REST API between human+browser and machine. So when designing a website you don’t think of https://www.beatport.com/checkout/thanks as an endpoint, it’s the thanks page.

Web designers chose a friendly URL, and the HTML resource representation makes for the best experience for a human-interface, while affording an onward journey via a new set of hyperlinks.

If you talk in endpoints, then you are tempted to argue, why do I need a special endpoint for thanks?

I could hit an endpoint to say I accept what’s in my cart, and then just draw the checkout on www.beatport.com. Of course that sounds absurd now, but this funny kind of thinking sometimes happens when we’re talking about data, endpoints and “REST” APIs.

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.

I now intend to apply for this insurance quote.

What should the URL of my API be for this course of action? On which other resources should we link-in from? What would it present to help me reach my goal? Does the application need to collect further information from me? And can it do all that using only information in the URL?