Agreed.

That was one of many lessons we learned with v2. Now we have a way to state the canonical URL for the metadata doc, but originally we just used it as the one well-known URL (we left the behavior of the service root undefined, figuring that services would want to do things with that).

Turns out we were wrong, and people wanted `/` to give a standardized service doc that has a ref to the metadata doc. So now we have both (for back compat).

Arlo

From: api-craft@googlegroups.com [mailto:api-craft@googlegroups.com] On Behalf Of mca
Sent: Monday, April 09, 2012 3:29 PM
To: api-craft@googlegroups.com
Subject: RE: One Meta URL to Rule Them All?

IMO, a better approach if too use "meta" affordance. Clients can recognize the control and servers are free to use any URL they wish including ones in other namespaces (domains) and URLs that match languages, etc.

Mike Amundsen
On Apr 9, 2012 6:22 PM, "Arlo Belshee" <Arlo.Bels...@microsoft.com<mailto:Arlo.Bels...@microsoft.com>> wrote:
This is exactly the approach we took with OData. Worked reasonably well.

We found there were good reasons to not put the metadata at root. Similarly, we didn't want to corrupt the API surface (since we were making an API for arbitrary services). So we named the metadata `/$metadata` (by default convention - a link from the root provides the real value).

There are still a whole bunch of details to work out from there (such as what does $metadata contain?). Most of the design at this point was in-house, so I'm not sure how much you'll be able to glean from the old blog posts (which don't go back before 2010 anyway).

However, most of the designers who were thinking this stuff through prior to 2010 are still with us. They'd be happy to share some lessons learned if you wanted.

I am definitely in favor of using metadata to drive a web API. It can make the system open for client extension, while still leaving the server in control of what's allowed and how that is done.

There are just a ton of details involved in getting it right - many of which we learned by getting them wrong and then having to fix it while maintaining backwards compatibility even on the metadata document.

Arlo

From: api-craft@googlegroups.com<mailto:api-craft@googlegroups.com> [mailto:api-craft@googlegroups.com<mailto:api-craft@googlegroups.com>] On Behalf Of Mike Schinkel
Sent: Monday, April 09, 2012 2:15 PM
To: api-craft@googlegroups.com<mailto:api-craft@googlegroups.com>
Subject: One Meta URL to Rule Them All?

Changed the subject to recognize the change in topic.

On Apr 9, 2012, at 4:39 PM, Jørn Wildt wrote:

Unfortunately those indirections can be expensive in too many use-cases, such as for mobile devices.

Good point. The problem can, to some extend, be mitigated by caching and use of ETAG for conditional requests. Then you only pay the penalty once - probably at the time of installing the mobile app in which case you should have plenty of bandwith.

Here's a thought that I wonder if anyone is considering?

Rather than encoding the link templates into each response, what about offering them via an API-wide resource that could by-convention be retrieved from the API root:

{
    "_signature": "Web API Meta v1.0",
    "_self": "http://api.example.com",
    "_meta": "http://api.example.com",
    "root": "http://api.example.com",
    "vars":[
                {name:"event_id"}
    ],
    "uris":[
                {id:"events", "uri":"/events"},
                {id:"event", "uri":"/events/{event_id}"},
                {id:"event_photos", "uri":"/events/{event_id}/photos"}
    ]

That would mean the client only needs to request the meta once.  This approach could of course be extended to include external references in the meta response for those huge APIs where it's too big to force mobile devices to download, much how conceptually a sitemap.xml can be partitioned into multiple files.

Further, the root could indicate another resource for meta if need be,

{
      "_signature": "Web API Meta v1.0",
      "_meta": "http://api.example.com/meta",
      "_self": "http://api.example.com",
      "other": "stuff",
      "goes": "here."

Individual responses could provide a link back to their meta data, but it would be *optional*:

{
    "_meta": "http://api.example.com/meta",
    "event_id": abc123,
    "event_name": "Easter Egg Roll",
    "event_location": "South Lawn, The White House, Washington DC"

Another benefit of this approach is that it would layer over any existing API, i.e. Twitter's.  And that would allow someone to create a meta file for any existing API that could be made available to the client even of the API provider does not support HATEOAS.  So if I want my client to be hypertext driven I can even hardcode into my client the meta for a given API that is not HATEOAS and/or I could code my client to retrieve the meta from my own servers in the case I want my client to be more resilient to change.

This approach would allow good tools to emerge because it's an incremental approach; it doesn't try to boil the ocean.

Thoughts?

-Mike
P.S. I know there are many here on this list who are advocating a prescriptive approach so I don't expect you to embrace this idea. But at least give it some serious thought?