Name: translator-api-registry
Owner: NCATS Data Translator Project - Tangerine Team
Description: This repo hosts the API metadata for the Translator project
Created: 2017-06-21 17:43:37.0
Updated: 2017-10-19 16:54:47.0
Pushed: 2018-01-10 21:18:43.0
Size: 336
Language: Python
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
This repo hosts the API metadata for the Translator project
If you have the permission, commit your changes to this repo. Otherwise, feel free to submit a pull-request. Please check the “build status” badge above, and make sure it's green after your changes. We run some validation tests in this “tests.py” for each commit. (Tip: you can run python tests.py locally from the root of this repo to make sure all tests pass before you commit your code.)
You can use this editor to write/edit your API metadata. You can start with an existing metadata example from “mygene.info” or “myvariant.info” APIs. The editor automatically validates your API metadata and gives a live preview of auto-generated API documentation.
This OpenAPI GUI interface can also be useful for creating your API metadata from the scratch. But be aware of that this interface does not support any SmartAPI extensions (those fields with “x-” prefix) we added to the standard OpenAPI v3 specifications. You can of course add extra SmartAPI fields after you export your metadata from the GUI interface to the editor.
If you already have an API metadata document in older Swagger/OpenAPI v2 specification. You can try this conversion tool to convert it to the latest OpenAPI v3 format, and then edit it in the editor:
http://openapi-converter.appspot.com/ (this link is dead, use the new one below) http://openapiconverter.azurewebsites.net/
This converter is not perfect, but still a good starting point.
Tip: Feel free to play with your API metadata file with the tools we mentioned above, and commit your changes even when they are not fully complete or valid. As along as the metadata entry has not been added to the API_LIST.yml file (see below), you will be fine :-). When you are happy with your metadata, you can now move to the next step to add it to the API_LIST.yml file.
A code snippet to convert flask-restful auto-generated swagger v2 specification to SmartAPI metedata, kindly provided by @JohnCEarls.
This is a YAML file at the root of this repo to keep track of all APIs available in this repo. Our SmartAPI application will import all the API metadata based on this file and render an API registry web frontend.
For each API, you just need to add a text block like this:
- metadata: mygene.info/openapi_minimum.yml
translator:
- returnjson: true
notes: ""
metadata field
The value of this field should be either the URL or the relative path pointing to the API metadata. The API metadata should follow OpenAPI specifications, in either JSON or YAML format. Specifically, we support OpenAPI v3 specification documented here, plus the SmartAPI extensions documented here.
translator field
This serves as the placeholder for any translator project specific API properties, e.g. adding some API-specific notes.
How to propose a new translator.* field?
As we expand our list of APIs, we will need to expand our metadata fields as we needed. To do so, you can:
If you want users are able to request your API from the browser, e.g. in a web application, your API should support CORS. We recommend every translator API to support CORS. Depending on your web server (e.g. Apache or Nginx) and/or the web framework (e.g. Django, Flask, Tornado) you use, you can find the relevant instruction to enable CORS for your API here, or via Google.
Typically for a JSON-based REST API, we use URIs to annotate both the acceptable parameter value types and the fields from the response data object, both in OpenAPI metdata files and JSON-LD context files. You can find some examples for “mygene.info” and “myvariant.info” APIs.
To help you decide which URIs to use, we maintain a “ID_MAPPING.csv” file to keep records of all URIs we will use. Feel free to add URIs for additional field types. Please make sure not to break the csv format, as that will break github's nice csv rendering and search features.
In general, we like to use the URIs from these repositories (also in that priority order)?