Is there a way to discover all endpoints of a ReST API?

Question

I'm wondering if its possible to programmatically discover all the endpoints of a particular API.

So for example if I GET this URL with a browser or curl: https://api.twitter.com/1.1/

I might get something like this as a JSON response:

{"TwitterAPI":{
    "version" : 1.1,
    "GET" : {
        "search/" : ["users", "trending"],
        "users/" : ["id", "handle"]
    }
}

Of course Twitter could choose to publish or not publish this format. So as a side question, are there any libraries for Java or Javascript that will automatically map and publish the API routes you created in your controllers?

Solution 1

There is no way of programmatically discovering REST services as they do not have a standard registry service.

Apart from doing something insane brute-force search there is no way of finding the right URLs ( not to mention the right parameters). So the only option is documenting your API. For that the best choice I have seen so far is:

• Swagger
• And people also like API Blueprint.

Solution 2

Some RESTful APIs publish a Web Application Description Language resource (WADL - pronounced like the walk that ducks do - for short). JAX-RS, or at least Jersy webapps will do this by default at the application root URL /application.wadl. It doesn't appear that Twitter's API is one of these. Many REST purists would argue that the API should be self describing and self discoverable simply by interacting with it and seeing what other endpoints it will give you.

More about WADL from wikipedia...

Solution 3

You should be able to discover everything you need to know about a REST API by only knowing the initial entry point. This is one of the fundamental points of REST; that it should be hypermedia driven and self describing. It is also one of the least understood principles. The discovery of resources is down to hypermedia links in the responses from the server.

Back as long ago as 2008 Roy Fielding started to get annoyed about people writing HTTP based APIs and calling them REST just because it was the hot new thing. Here are a couple of points he makes;

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC’s functional coupling].

and

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

What this means in practice is that the entry point (typically using the root URI of "/") contains links to other REST APIs. Those APIs will contain links to other APIs and so on. There should be no API that doesn't have a link to it. That would mean it is not discoverable.

The other answers here fundamentally wrong in that they fail to acknowledge the most basic principle of REST.

Solution 4

There is a way to get most of the hidden REst-Apis from inside of the website.Follow this documentation.

View more solutions

Comments

[4m1r]

Great answer thanks for the reference! The WADL answer below is great too, but I think these suggestions are a bit more useful.

[4m1r]

actually, gonna leave this unanswered for a few and see if we can't get a few more useful answers.

[Stargateur]

You are hurting a conflict between practice and theory, the true is user always win. Rest is more what you call guidelines, than actual rules.

[MoltasDev]

How would one go about to actually see said links?

[Admin]

Your answer could be improved with additional supporting information. Please edit to add further details, such as citations or documentation, so that others can confirm that your answer is correct. You can find more information on how to write good answers in the help center.

[brichins]

The self-describing aspect is not generally used in practice, but here's more reading on the definition - en.wikipedia.org/wiki/HATEOAS (short for "Hypermedia as the Engine of Application State")

[Dustin K]

Isn't one of the constraints of a REST api is "code on demand". If you can't dynamically discover endpoints, then is it really RESTful?