smartapi/smartapi-ld

Vocabulary resources in support of semantics and linked data

SmartAPI

Intelligent APIs for a more connected web.

A BD2K/Network-of-BioThings project.

SmartAPI allows API publishers to annotate their services and input/output parameters in a structured and identifiable manner, based on a standard JSON-LD format for biomedical APIs and services. By indexing and visualizing these descriptions as Linked Data in a Elasticsearch back-end, researchers can seamlessly identify the services that consume or return desired parameters, and automatically compose services in workflows that yield new insights.

Presentation: http://bit.ly/smartAPIslides
Contact: [email protected]

How to run a dev API server locally

1. Install Elasticsearch (version 7.x) at localhost:9200 (follow this instruction) or install with docker (follow this instruction)

2. Clone this repo

   git clone https://github.com/SmartAPI/smartAPI.git
   

3. Install system packages (on Ubuntu, for example)

   sudo apt install libcurl4-openssl-dev libssl-dev aws-cli
   

4. Install python dependencies after navigating to root smartAPI directory

   cd smartAPI
   pip install -r requirements.txt
   

5. Navigate to SmartAPI source files and create a config_key.py under src

   cd src
   touch config_key.py
   

6. Update config_key.py with

   COOKIE_SECRET = '<Any Random String>'
   GITHUB_CLIENT_ID = '<your Github application Client ID>'
   GITHUB_CLIENT_SECRET = '<your Github application Client Secret>'
   SLACK_WEBHOOKS = [ 
       {
   	    "tag": '<string>', # (optional)
   	    "webhook": '<insert webhook URL>'
       }
   ] # (optional) 
   

   For Github incorporation, follow this instruction to create your Github Client ID and Secret.
   Enter any Application name, http://localhost:8000/ for Homepage URL and http://localhost:8000/oauth for Authorization callback URL.

   For SLACK_WEBHOOKS (optional), the list may not be included if one does not want Slack notifications pushed every time a new API is added to the smartAPI registry.

   Alternatively, if one wants slack notifications sent to more than one channel, one may list more than one dict in the SLACK_WEBHOOKS list.

   Follow this instruction to create Slack webhooks and obtain webhook URLs.

   If one would like a Slack notification pushed only if the newly registered API contains a specific tag, one should include the tag key, which should have the value of the specific tag (case sensitive).

   For example:

   "tags": 'translator' # will send every time an API is registered with a 'translator' tag 
   

7. Optionally import some API data from a saved dump file. Contact us for the dump file.
   And replace the name of the file in the command with the backup file name.

   import admin
   admin.restore("smartapi_oas3_backup_20200706.json")
   

8. Run dev server

   python index.py --debug
   

You should now able to access API dev server at http://localhost:8000

Note: On windows with python 3.7, if you cannot install pycurl automatically, try downloading a pre-compiled binary and install manually from https://www.lfd.uci.edu/~gohlke/pythonlibs/

smartapi-ld's Issues

Add signpost in HTTP header

As far as I understand the metadata of the API should be kept in a repository according to the paper. I have a suggestion: I think that in the API response, the Link HTTP header would be a good place for a URL pointing to the smartAPI description. Herbert van de Sompel suggested this method in his Memento [1] and Signposting [2] initiatives, and I think the idea could be reused here as well. Signposting already suggested to use the "describedby" relation to bind object and metadata description. Van de Sompel gives the following usage example (in the context of an institutional repository):

curl -I "https://doi.org/10.1007/s10958-016-2844-8"

Link: https://doi.org/10.1007/s10958-016-2844-8
; rel="describedby"
; type="application/vnd.citationstyles.csl+json"

In a smartAPI it would be something like that

curl -I "https://example.com/smartAPI?...."

Link: http://smart-api.info/api/metadata/...
; rel="describedby"
; type="application/json; charset=UTF-8"

This kind of link would help the discoverability of the API metadata, and thus the life of the developers of API clients, who might be not aware of the existence of smartAPI documentation, but check the HTTP headers routinely.

[1] the most recent paper I read: Sande - Verborgh - Hochstenbach - Sompel, Toward sustainable publishing and querying of distributed Linked Data archives (Journal of Documentation, 2018) http://linkeddatafragments.org/publications/jod2017.pdf, and Miel van der Sande's doctoral thesis at https://biblio.ugent.be/publication/8551528

[2] http://signposting.org/

Best,

Péter

---

Péter Király
GWDG - Gesellschaft für wissenschaftliche
Datenverarbeitung mbH Göttingen
Am Faßberg 11, 37077 Göttingen
www.gwdg.de