Create metadata for a Translator API Catalog

[mbrush]

At present there is no comprehensive and up to date catalog of Translator APIs that provides high-level description of the content and accessibility of data served by each. This has been a barrier for many Translator efforts.

We are asking an API developer or representative to complete a short metadata record describing their API. The schema and templates provided below should allow contributors to enter metadata in 15 minutes or less, and we aim to have complete records for all translator APIs by the end of the Jan 2018 Hackathon.

The metadata in this catalog is intended to complement the more granular metadata collected in the smartAPI registry, to provide summary-level information about the content, accessibility, and utility of each API for technical and non-technical users.

Collection of this metadata will be coordinated with Translator smartAPI registry efforts. Specifically, we will extend the yaml format used the existing API_LIST.yml file with additional fields, as defined in the schema.yaml file.

---

Instructions for creating a metadata record:

1. Go to the API list at http://bit.ly/apicatalog and add your name to the sign up sheet.
2. Review the schema.yml file, and the example_metadata.yml completed record.
3. Copy text from either the example_metadata.yml record or this template.yml file, and overwrite it in a new file with metadata about your API.
4. Name your metadata file [api name]_metadata.yml and commit it to the api_catalog/records folder in the translator-api-registry repo.

Notes:

1. If a particular field does not apply to your API, enter 'null' as the value.
2. Value set enumerations for fields with controlled entry are provided at the end of the schema.yml file.
3. Feel free to extend the 'Entity Type' value set (ENUM3) directly in the schema file and commit it back with these changes. However, all other value sets are not directly extensible - if you want to alter these value sets please make a ticket proposing the change/extension.

I will hold 'office hour' sessions for at least one hour each day at the hackathon to answer questions and take feedback about the metadata schema and process. Additionally, questions or feedback can be recorded as comments on this ticket.

Once completed, I will merge the content of each API's metadata file into the API_LIST.yml file. From here we can automate derivation of various artifacts (e.g. a spreadsheet view for easier viewing/filtering).

[mbrush]

Note that the list of API list at http://bit.ly/apicatalog may not be complete, and may contain APIs that are no longer active/relevant. It was pieced together from info found at three sources:

1. An early Translator API spreadsheet.
2. The translator-api-registry API_LIST.yml file.
3. Any APIs listed in the smartAPI registry that had a 'translator' tag.

Please add/remove APIs to the spreadsheet as appropriate.

[mbrush]

We'd like to find a way to collect this metadata quickly or the Translator use case, but also coordinate with smartAPI so that some of the new metadata element can be incorporated into their spec at some point (ideally everything can get rolled into smartAPI). Making a tentative proposal below:

At the Hackathon:

1. Create a minimal smartAPI spec similar to this proposal.
2. Refine the proposed translator metadata schema by removing any elements found in the smartAPI minimal spec, such that it only contains the new elements proposed for the Translator use case.
3. Request that Translator API developers at minimum create a smartAPI record using the minimal spec (if they haven't already created a full record)
4. Request that developers also create a translator metadata record according to the translator metadata schema, which will live in the API_LIST.yml file along with other translator-specific metadata there. We can collect feedback and refine this spec during this process.

After the hackathon we can explore how some or all of the translator-defined elements or value sets could be incorporated into the smartAPI spec. If this happens, we could then move metadata for these elements from the API_LIST.yml file into the official smartAPI spec for each API.

[micheldumontier]

Here's a gist for moving most of what was in your first spec : https://gist.github.com/micheldumontier/97842b604212b89af9bb715a39d5c39a

we need to come up with a proposal how people will select entities, entity attributes, and entity relations. i have an idea on the structure, but we need to know how the master list will be composed, and whether it will use any existing ontologies. are we just going to create yet another vocabulary?

[mbrush]

Hackathon outcomes for this pitch noted in gdoc here:
https://docs.google.com/document/d/1Y8ZZcuMgX0evAsF3g_yMpT0J46gAM0RBqHYDiDZkLns/edit#heading=h.m6xwhjiuijh5