The Link header [1] works very well for this. It exports an index of links with the same semantics as the <link> element.

  <link rel="stylesheet" href="/styles.css">

But in the header, which means API consumers don't have to search the response body for links, and can specifically request the index with a HEAD request.

  Link: </styles.css>; rel="stylesheet"

The reltype is pretty powerful - it enables semantic standards and lets a client make assumptions about endpoints. Since the Link header is a standard format of, you know, links, it's also very discoverable.

1. http://tools.ietf.org/html/rfc5988

EDIT: hm. No idea why I got downvoted, but I tightened it up to get more to the OP's point.

Your first and second sentences contradict in a way which illustrates the challenge: interface discovery is trivial but that only helps with the lowest-level part of a client library.

There's a great Python library called UniversalClient which illustrates this nicely: it provides some helpful scaffolding for working with REST APIs and structuring your code in a maintainable manner but ultimately a programmer still has to provide the service-specific understanding:

https://universal-client.readthedocs.org/en/latest/basics.ht...

> What is needed is a standard for discoverable RESTful interfaces. With that, there could be a single client library for each platform/programming language to access any compliant API.

I don't get how that would work magically. Imagine that I want to update my phone number in my account data on two different sites. If I point this magical library at the two site's APIs, how would it decide which resources to update under which paths?

It seems to me that you would still need to implement the different concepts, resource names, and so on across different sites, and you wouldn't really win anything here.

You mean SOAP and WSDL? Or perhaps Rails ActiveResource? Or perhaps http://xkcd.com/927/?

No, you don't a different browser, but you need to know how to use the sites of both banks. You can do that because you have a brain. How should code know to navigate the APIs of different providers without the code knowing the tasks to accomplish? It cannot decide for itself.

I have seen this example before, but to me this neglects the aspect of using human intuition to understand how to, for example, send a wire through Citibank's site vs BofA's site. Without being argumentative, I think want to understand how this applies to APIs? (i.e. How could Citibank's hypothetical RESTful API teach my code how to send a wire transfer through their system if I had been using BofA for all previous transactions?) Or am I just flat-out missing a bigger point here?

I've been working on something very similar to what you are describing: http://www.cosmic-api.com I would really appreciate some feedback :)

Looks nice. To really evaluate it, I need to see what the HTTP endpoints and traffic look like. My concern is what experience a non-cosmic client would have.

Some banks work only with IE...

Hm really? I can't imagine a bank in 2014 getting away with this, at least for consumer-facing services. They are just going to write off all their mobile customers?

If you're talking about B2B or other more back-end type stuff, yeah some of this is annoyingly outdated. My bank's "business bill pay" website looks like it was written in 1998 and not changed since.... it does work in FF and Chrome though, since it's just bare-bones html forms and almost no javascript.

No, consumer facing websites. I work closely with a Service Desk department. I've dealt with having to get major bank websites up and going one too many times!

I have an even better strategy, instead of dealing with all this bullshit manufactured complexity and artificial scarcity, throw all that shit away and use basic web sockets like everyone already does, and save a fortune in time and money in the process. On top of that, you don't even have to support bullshit metadata protocols that do nothing but add overhead and implementation complexity, but are sold on being dynamic and secure, when the only thing that is dynamic is their product support and latency and the only thing that is secure is how fucked you are when your account is canceled.