CODEWITHSUNDEEP
apiresthyperlink
Franz Deschler
Franz Deschler

Reputation: 2574

Is there a REST API documentation that only publishes the root URL?

I´m trying to design a REST API for my application and I read a lot about best practices and how REST is supposed to work. One of the most important topics about REST is, that the resources should be linked via references and the client should only know the root URL of the API.

But I cannot find any API documentation that really does this. Every REST API documentation I ever read on the web shows an exact description of the URLs of the possible endpoints.

Is there any API documentation out there that only shows the root URL and describes how to navigate through the resources?

Upvotes: 0

Views: 152

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57377

One of the most important topics about REST is, that the resources should be linked via references and the client should only know the root URL of the API.

The root URL and the media types, yes. The client needs to know where to start, and also how to interpret the responses it gets.

Your primary example of a REST API would be the world wide web. You point your browser at www.google.com, and then you just follow links and submit forms until you get the result you want.

Another REST API that might be familiar is Atom Syndication / Atom Pub.

More academically, there is RESTBucks. That paper was somewhat popular, and you can find a number of sample implementations around.

Jon Moore (2011) presented a good demonstration of a hypermedia API.

Every REST API documentation I ever read on the web shows an exact description of the URLs of the possible endpoints.

Yes; bad examples are much more common than good examples.

Upvotes: 1

Related Questions