Getting Started With SenNet APIs

Some data is not accessible to the public, for non-public data, you will need an authorization token. Easily grab a token by first logging into the SenNet Data Sharing Portal. Then navigate to your user menu on the top right. Select Copy Globus Token. This will copy the active token to your clipboard for later usage.

Making your first API request

Now that you have a token, let’s make a simple request to retrieve data about a given entity. The endpoint that handles that request is /entities/<id>. You will need to build the full url to be requested against the domain base for the service which the endpoint belongs to, in this case, that’s the Entity API. The domain base for the Entity API is https://entity.api.sennetconsortium.org. For a full list of API services see the APIs page. Given a Source with UUID 2f2a7af9951f50b399d76b5080486fe1 (SenNet ID SNT722.BGFJ.623), data about this entity can be requested using the following code below.

import requests
import os
import json
domain_base = "https://entity.api.sennetconsortium.org" 
headers = {
    "Authorization": "Bearer COPIED_TOKEN_HERE",
    "Content-Type": "application/json"
}
endpoint = "/entities/2f2a7af9951f50b399d76b5080486fe1"

query_url =  f"{domain_base}{endpoint}"
entity_data = None
try:
    #make request and grap the HTTP response code
    response = requests.get(query_url, headers=headers)
    response_code = response.status_code

    if response_code == 200:
        entity_data = response.json()
    else:
        print(f"An error occurred {response_code}")
except Exception as err:
    print(f"An unexpected error occurred: {err}")

You may want to write this response data to a file. You can do so with the following code:

if not entity_data is None:
    file_name = "entity_data.json"
    with open(file_name, 'w') as file:                                                                                           
        file.write(json.dumps(entity_data))
    print(f"manifest file written at: {os.path.abspath(file_name)}")
else:
    print("ERROR: No entity data information found. File not written")

Using Smart API to test the APIs

Most of the various SenNet API services have accompanying full documentation via Smart API. For our example above, we could also make use of the Smart API Try It Out tool to check entity data. To do so, follow the steps below.

1. Navigate to the /entities/{id} endpoint.
2. Click Authorize on the top right  
3. Paste your bearer token in the modal Value: field  
4. Click the Authorize button in the modal  
5. Then in the /entities/{id} section, click Try it out  
6. In Parameters area, paste the entity’s id UUID or SenNet ID the id field  
7. Then click the Execute button  

A 200 response means a successful result. A 404 response means that the entity was not found. Per endpoint, the Responses section describes the various response codes that could occur.

And that’s all it is. For a complete guide per service, visit the APIs home page and navigate to the usage links for the API you wish to query.