SmartAPI and OpenAPI
SmartAPI uses OpenAPI-based specification for defining the key API metadata
elements and value sets.
SmartAPIs leverages the Open API specification V3 and JSON-LD to provide
semantically annotated JSON content that can be treated as Linked Data.
Resources
extension SmartAPI Extensions
Most of the SmartAPI extensions are optional, but a few are REQUIRED, for example:
info.termOfService
info.contact.x-role
info.version
For a full list of REQUIRED extensions refer to the recommendations column of the document here:
Start From Scratch
-
Create and Edit Your V3 OpenAPI Metadata
You can start with an existing metadata example below. The editor automatically validates your API metadata and gives a live preview of auto-generated API documentation.
Metadata Examples
API EDITORNote: This OpenAPI GUI interface can also be useful for creating your API metadata from scratch. But be aware 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. You will add those extensions at a later step.
For a complete list of SmartAPI extensions, visit this link:
Extensions -
Done Creating Your V3 Metadata?
NEXT
Version 2
If you already have an API metadata document in older Swagger/OpenAPI V2 specification you will need to follow these steps to convert your metadata to the latest OpenAPI V3 format, and then edit it in the editor below.
warning You may submit your V2 metadata as it is up to this point, however you will experience limited functionality.
Learn More about OpenAPI V3 SpecificationWe recommend you continue with this process to convert your metadata to OpenAPI v3 metadata to be fully compatible with SmartAPI and BiotThings Explorer.
-
code
CONVERT YOUR METADATA:
Use any of these two options to convert your V2 Metadata to V3 Metadata.
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.
-
Done Converting Your Metadata?
NEXT
Version 3
Validate Your MetadataValidate your metadata and clear all errors using this editor: Editor |
Host Your MetadataHost your metadata in a version-control system. On your own Github repository or on our project specific repositories. Hosting Info |
Add Required SmartAPI ExtensionsMost of the SmartAPI extensions are optional, but a few are required, for example:
For a full list of required extensions refer to the recommendations column of the document here: Extensions |
Completed All Steps?NEXT |
You're Ready To Submit Your Metadata!
Add Your APIImportant! Before submitting make sure to copy the URL to the RAW content!

Hosting
Host Your Metadata With Us
The link below provides an optional place for those who need to have a place to host their own API metadata.
-
1Each API should create a separate folder to host its metadata. The folder "_example_api" provides a basic template for adding API metadata, so you can start with copying the "_example_api" folder and renaming it to your API name.
-
2Fill in the metadata about your API according to the instructions. Also, please refer to the existing examples like mygene.info and myvariant.info APIs.
-
3Add an entry to the API_LIST.yml file following the existing example. This is the master list of the APIs available in this repo. Our SmartAPI application will import all the API metadata based on this file.
-
Choose the appropiate project to host your metadata under:
Advanced
CORS Support
If you want users to be able to request your API from the browser, e.g. in a web application, your API should support CORS. We recommend every public 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.
How to choose URIs for annotating API input/output
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 SmartAPI metdata files and/or JSON-LD context files.
To help you decide which URIs to use, we maintain an 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.