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?
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:
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.
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.