Re: Request for well-known URI: contribute.json

[Paul McLanahan <[e-mail]>]

-----Original Message-----
From: Roy T. Fielding <[e-mail]>
Reply: Roy T. Fielding <[e-mail]>
Date: October 10, 2016 at 1:42:34 PM
To: Paul McLanahan <[e-mail]>
Cc: [e-mail] <[e-mail]>
Subject:  Re: Request for well-known URI: contribute.json

> FWIW, reserving a universal location for this purpose doesn't make any sense.
> It is common for a single hostname to provide many different open source projects.
> Even an Apache project will often have multiple product-specific pointers to
> contributions within the same project-specific hostname.

We're working on adding sub-project contribute.json discovery to the schema[0].

> The well-known URIs are intended for protocols that do not want to access part
> of a site's normal resources. In particular, when the only thing a client knows about  
> a site is a URI that it does not want to access before knowing something more about
> the site or its communication options.

The clients of the contribute.json files will be mostly that. It will be scripts that aggregate contribution information or other web crawlers. It should be used in much the same way search bots discover and use robots.txt.

> In this case, the client already knows the home page of an open source project.
> There is no reason for that client not to GET the homepage. The data in this resource
> is commonly found in (or near) the homepage. So, the only thing you are providing
> is a structured record in a common format. You can do that within the homepage
> using a standard JSON object, a standard profile of HTML elements, or even an
> embedded link with a standard relationship.

It's difficult, impractical, or wasteful to parse HTML in some situations. Having an easily parsable JSON document in a known location really helps to gather this information, especially from JS in a purely client-side application.

> When that data is in the homepage, there is no need for a separate request, and
> the data itself is less likely to become stale over time. It also allows a
> single host to have more than one distinct open source project.

As I said above, the expectation is that most clients won't have already requested the home page. Some obviously will (e.g. a browser extension), but moving the data into the HTML makes the other clients much more difficult to write and maintain.

[0] https://github.com/mozilla/contribute.json/issues/71#issuecomment-251841553

Thanks very much for your feedback,

Paul McLanahan
Mozilla