API Endpoints

[stuartpb]

• There should be an API that gives a list of domains that are profiled, and the hash/ETag of its source material.
• There should be a list of every domain that has a "use" record, and what the value of that record is.
  • We could also have just generalized sideways record querying, so you can get all the records for any field. We could even memoize them (though this could have the potential to make RAM blow up).

Tentative routes:

/v0/1/etags

Object of all domains that are profiled, and the hash/ETag of its source material.

/v0/1/domain/:domain

Gives a 404 if the domain does not exist. Domain-collapsing logic is expected to be handled by the client.

Maybe takes a query string that allows for subset requests. Maybe. (I kind of feel "select" handles that better, although it's true that the data can mismatch between requests if the server failovers to a newer version between requests for two distant fields from a select.)

/v0/1/select/:field

Returns all domains with the field specified, and what the value of that field is.

/v0/1/profiles/domains

Gets everything (domainprofiles.json).

[stuartpb]

As for versioning (beyond what was just posted on #7), I don't think there'll be any surfacing of it beyond the routes' version prefix, since schemas are either distinguished by that prefix, or they're forward-compatible. Minor-version stuff is an implementation detail.

In the event that you're coding against endpoints that may potentially not support minor-version features, you're probably already in a situation where you need to duck-type-test for feature support and fallback behavior.

[stuartpb]

What about subdomain-varying profiles (#29)? The API could maybe synthetically manufacture those when requested as JSON, maybe with a "from:" field that points to the higher-level domain.

[stuartpb]

Implementing the API is going to be a bit hairy, and isn't needed for all the data-centric changes that need to happen for this to be usable and publishable. Kicking this to future.

[stuartpb]

I think, better than /profiles/domains and /domains/:domain, we should have /domains/:domain and something like /all/domains. (Calling the "all" route "profiles" doesn't make a lot of sense.)

As for selection, I think that should really be a query parameter (since, y'know, it is a parameter of the query) - and have that string apply for whatever route returns results for all domains.