SmartAPI
{{progressText || '0%'}}
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.

Learn More
GUIDE

ADD YOUR API


START

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:

Open on Github

Do You Have OpenAPI Metadata?

YES NO

Back to Introduction

Go Back

Which Version Do You Have?

Version 2 Version 3

Don't Know Which Version You Have?

Version 2
swagger v2

Visit the links below for examples and version specification.

V2 Example
V2 Specification
Version 3
openAPI v3

Visit the links below for examples and version specification.

V3 Example
V3 Specification

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 EDITOR

    Note: 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.

Submit Swagger V2 Metadata

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.

  • code

    CONVERT YOUR METADATA:

    Use any of these two options to convert your V2 Metadata to V3 Metadata.

    Tavis OpenAPI Converter

    Converter 1

    Mermade Converter

    Converter 2

    Other Conversion Tools:

    Api-Spec-Converter
    npm package

    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 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:

  • info.termOfService
  • info.contact.x-role
  • info.version

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 API

Important! Before submitting make sure to copy the URL to the RAW content!

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.

  • 1
    Each 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.
  • 2
    Fill in the metadata about your API according to the instructions. Also, please refer to the existing examples like mygene.info and myvariant.info APIs.
  • 3
    Add 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:

    NCATS Translator Project

    NCATS More Info
    SmartAPI Project

Advanced

developer_board

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.

settings_ethernet

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.