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.
What is OpenAPI?
The OpenAPI Initiative (OAI) was created by a consortium of forward-looking industry experts who recognize the immense value of standardizing how REST APIs are described. As an open governance structure under the Linux Foundation, the OAI is focused on creating, evolving and promoting a vendor-neutral description format. SmartBear Software is donating the Swagger Specification directly to the OAI as the basis of this Open Specification.
APIs form the connecting glue between modern applications. Nearly every application uses APIs to connect with corporate data sources, third-party data services or other applications. Creating an open description format for API services that is vendor-neutral, portable and open is critical to accelerating the vision of a truly connected world.
What is SmartAPI?
The smartAPI project aims to maximize the FAIRness (Findability, Accessibility, Interoperability and Reusability) of web-based Application Programming Interfaces (APIs). Rich metadata is essential to properly describe your API so that it becomes discoverable, connected, and reusable.
What is the relationship between Swagger Specification and OpenAPI Spec (OAS)?
SmartBear donated the Swagger Specification in 2015 as part of the formation of the OpenAPI Initiative. Following the announcement of the OAI, the Swagger specification was renamed the OpenAPI Specification and is semantically identical to the specification formerly known as the Swagger 2.0 specification.
OAS – and the Swagger Specification before it – is widely recognized as the most popular open source framework for defining and creating RESTful APIs, and today tens of thousands of developers are building thousands of open source repos of tools leveraging the OpenAPI Specification.
ADD YOUR API
extension SmartAPI Extensions
Most 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:
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 Specification
We recommend you continue with this process to convert your metadata to OpenAPI v3 metadata to be fully compatible with SmartAPI and BiotThings Explorer.
CONVERT YOUR METADATA:
Use any of these two options to convert your V2 Metadata to V3 Metadata.
Tavis OpenAPI ConverterConverter 1
Mermade ConverterConverter 2
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?
Validate Your Metadata
Validate your metadata and clear all errors using this editor:Editor
Host Your Metadata
Host your metadata in a version-control system. On your own Github repository or on our project specific repositories.Hosting Info
Add Required SmartAPI Extensions
Most 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?
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:
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.