Proposal for badge indexing API

badge-indexing-api.md

We need a lightweight way to make badge classes discoverable on a domain, so that we can build discovery tools like the Badge Codex.

Domains can advertise their badge classes by publishing a document at /.well-known/openbadge-classes.json. This JSON-formatted document must be served with the content type application/json.

Document Format

The document simply contains an array of domain-relative URLs representing BadgeClass JSON instances, like so:

[
  "/badge-classes/a-lister.json",
  "/badge-classes/code-whisperer.json"
]

Pagination

Clients accessing the document should check for a Link header. If it exists, the client may need to iterate through all pages via the next value for rel to obtain a full list of badge classes advertised by the domain.

Influences

This proposal was inspired by the following specifications:

• /.well-known/browserid
• Github API: Pagination

An alternative to providing a list of URLs to badge classes is to provide the actual BadgeClass structures inline. However, these structures don't contain URLs to themselves--thus the actual URL of the BadgeClass file would need to be provided out-of-band if the advertiser wanted to make it visible. Also, while inline structures may be easier for API clients to consume, they are potentially harder for the API providers to implement.

looks good to me.

Brian's servicefederation.md gist also has some good discussion on discoverability standards.