Create documentation APIs

[science]

We need APIs that provide inventories and metadata about system. For example:

/api/info gives metadata about the /api endpoint:

{
  "metadata_communities": ["http://#{servername}/api/learningregistry/","http://#{servername}/api/credentialregistry/"],
  "specification": "http://#{servername}/api/swagger#api"
}

/api/credentialregistry/envelope/info:

{
  "POST": {
    "accepted_schemas": ["http://{server}/api/credentialregistry/schemas/cti-credential-schema.json", "http://{server}/api/credentialregistry/schemas/cti-organization-schema.json"]
  },
  "DELETE": {
    "accepted_schemas": ["http://{server}/api/credentialregistry/schemas/envelope-delete-schema.json"] 
  }
}

[aspino]

Isn't this the same as what's implemented in #18? At least the first part about communities and documentation. Check this out: http://lr-staging.learningtapestry.com/api/

[science]

Indeed - sorry I missed that you implemented that! I'm adding a few additional features to that info system with the second part: the schema documentation. But yes @aspino it's pretty much the same.

How do you feel about using GET as the info source? Is that better than appending "./info" to the request to get information? I'm worried that some apis will rely on GET and so we won't have a good way of returning information consistently on various endpoints.. Thoughts?

[aspino]

I feel appending /info is a little bit redundant, because issuing a GET to a resource clearly reveals the intention that you want to retrieve information about that resource. But, as always, it's just a matter of preference. If you want to always use /info to be more consistent because other endpoints may use the resource's root path to return other, more important representations, then I guess it's fine.

[andersoncardoso]

I guess using GET directly on the resources would introduce some consistency issues as aforementioned.

To circumvent this, we could use a specific Content-type (something like application/vnd.learningregistry.apidoc+json). But on that case, we would be returning different information depending on the Content-type (instead just different representations of the same resource), which might not be good. Besides there is the overhead of changing headers etc.

Using */info might be better since it provides different data for different endpoints, and is easily 'browseable'.

We already do something similiar for json-schemas. Instead using "application/schema+json" on the same resource endpoints, we use /api/schemas/<something>

Just to illustrate the 3 cases:

1st case:

• / return info for /
• /envelopes return list of envelopes (where to provide info for envelopes?)

2nd case (same endpoint, different header, different info):

• / [Content-type: application/json] list of communities ?
• / [Content-type: application/vnd.lr.apidoc+json`] doc info for /
• /envelopes [Content-type: application/json] list of envelopes
• /envelopes [Content-type: application/vnd.lr.apidoc+json] doc info for envelopes

3rd case (different endpoints, different info):

• / list of communities ?
• /info doc info for /
• /envelopes list of envelopes
• /envelopes/info doc info for /envelopes

ps: info on this case is: accepted json-schemas, links for docs on swagger, metadata like counts and etc

If I missed some point or mistaken something let me know, tks

[science]

I'd say the inconsistent availability of GET requests (sometimes they perform a "real" api function sometime they return information) is the main problem.

I'll vote for 3rd case with one addendum. "/api" (the root) should probably return an HTML page - maybe the readme file, with maybe a link to /api/info. "/api/info" would return communities list and other root api data. And the rest of your suggestion for option 3 as listed.

That's my vote - I'll be curious if @aspino cares much (or @andersoncardoso if you have a preferred approach?).

Thanks for writing it up!