The Translator SmartAPI Registry
Overview
Members of the Translator consortium have created many web-based Application Programming Interfaces (APIs) to share knowledgebases and tools. Following its feasibility phase, the Translator Consortium endorsed the SmartAPI Registry as the standard online registry for such APIs. A dedicated â¨Translator SmartAPI Registry portal now provides access to:
- The â¨official registry of Translator APIs.
- Facilities to monitor SmartAPI metadata files and API endpoints for changes and availability to ensure that researcher access to reliable APIs.
- A â¨summary dashboard to view Translator APIs by:
- Endpoint uptime (eg. đĸ Pass, đ´ Fail, đ Unknown, đĩ Incompatible)
- SmartAPI file (“source”) status (eg. đĸ OK, đ Not Found, đŖ Broken, đ´ Invalid)
- By team, component (eg. KP, ARA)
- Compliance with required, Translator-related SmartAPI extensions
- A â¨Translator knowledgegraph visualizer (MetaKG) to browse and find Knowledge Provider (knowledgebase, also known as KP) APIs, based on desired relationships between biomedical entities.
About SmartAPI
The SmartAPI project aims to maximize the FAIRness (Findability, Accessibility, Interoperability, and Reusability) of web-based APIs. Rich metadata is essential to properly describe an API so that it becomes discoverable, connected, and reusable. The SmartAPI metadata specification is an OpenAPI-based specification that defines key API-metadata elements and value sets. It also uses JSON-LD to provide semantically-annotated JSON content that can be treated as Linked Data. After writing a SmartAPI metadata file for an API, that file can be registered in the SmartAPI Registry to make the API discoverable and reusable for others.
â Tip: SmartAPI provides an easy-to-use â API Metadata Editor to quickly get started documenting your API to the latest OpenAPI v3 specification.
Translator API Uptime Status and Source Status Monitoring
Each API in the â¨Translator SmartAPI Registry has a status badge indicating the overall status of the API based on all endpoints available for automated testing.
In the event of a failure, the Registry will provide a helpful error message so you can see the reason why a particular endpoint failed the monitor check. All of this can be managed via your â¨user dashboard in the Registry.
In addition to uptime status, each entry in the registry has a “source” status badge that tracks the status of the SmartAPI metadata file. âšī¸ Learn more about Source Status on SmartAPI.
To see a more detailed description of how SmartAPI tracks and monitors these statuses, you can visit the âšī¸Learn more about how SmartAPI monitors Uptime and Source Status from the SmartAPI Wiki and FAQ page.
Adding an API to the Translator SmartAPI Registry
First, a web-based API must be built for the knowledgebase or tool.
- â Build a REST API with JSON output (use your own preferred structure). Then work with the Service Provider team (see the Getting Help below) to write and register a SmartAPI file with the extensions needed for BioThings Explorer (BTE) to query your API and process its output. In some cases, you may also work with BTE’s team to get BTE to correctly process your API‘s output. This “wrapping” of your API with BTE will make your API compliant with various Translator standards (TRAPI formats and Biolink-Model semantics), which will make it usable within the Translator ecosystem of tools.
- â Design an API compliant with the Translator Reasoner Application Programming Interface (TRAPI) standard, add the required SmartAPI (Translator) extensions annotations to the resulting OpenAPI 3.0 yaml specification of your API, then register it in the SmartAPI Registry.
- â
Deploy your API into a specified
x-maturity-tagged server environment and add the endpoint to the servers block of the API.
Regardless of what your choice is, we recommend that you follow these â API best-practices.
â Tip: If you are using option 1, you may consider using the BioThings SDK from the Service Provider to build your APIs. BioThings SDK will create high-quality APIs following the best practices (linked above) by default. If you need help, please âī¸ contact the BioThings team (also members of the “Service Provider” team in Translator).
Translator-specific SmartAPI extensions
APIs in the Translator SmartAPI Registry must provide Translator-specific metadata in their SmartAPI metadata files.
- x-translator: global metadata for Translator project resources
- x-trapi: metadata about Translator Application Programming - Interface (TRAPI) implementations.
Registering your Translator API
To make registering a new API easier, the SmartAPI Registry provides a helpful â¨registration guide. This guide provides helpful links to examples, tools, and resources to help you write SmartAPI metadata files to document your API.
Once the SmartAPI metadata file for your API is ready, you can head over to SmartAPI and login using your GitHub account. Then head over to the Add an API page to register your tool. After successfully adding your tool, it will appear on your user dashboard, where you can manage anything related to your tool.
Getting Help
The SmartAPI team is available and ready to help you with any issue. If you need to contact us please open an issue here and someone will help you ASAP!