NanoInformaTIX

Database API access

revision 1.3.1

24 March 2023

Version history

Introduction

The NanoInformaTIX database can be programmatically accessed via an API. Because not all data in the database is public, just like with the web user interface, the API also requires user authentication.

At present, the following types of authentication are supported:

• API key, suitable for local applications (e.g. a Jupyter notebook), employed directly by the user
• OAuth2, for web applications, where third-party users will need to get authenticated

This short manual provides step-by-step instructions on how to configure the desired API access:

1. Accessing the portal
2. Obtaining an API key
3. Retrieving a forgotten API key
4. Configuring OAuth2

I. Accessing the API portal (1/3)

1. Make sure you can log in successfully at https://search.data.enanomapper.net. If you encounter any problems, please write to support@ideaconsult.net.
2. Go to https://api.ideaconsult.net and click the LOGIN link in the top right corner.

I. Accessing the API portal (2/3)

• Do not enter your credentials in the first login form. They will not work there—this is the local admin login. Instead, click on the Sign in with data.enanomapper.net button beneath it.
• A new modal browser window—Login with your data.enanomapper.net credentials—will open.
• Enter your username and password in this new window, and click “LOG IN”.

I. Accessing the API portal (3/3)

• If you get a red message “Wrong username or password”, make sure that you are entering the correct username and password. If the problem persists, please write to support@ideaconsult.net.
• Normally, the small window should disappear and you should see the following page, with the “NanoInformaTIX aggregated search“ box. Click on it.

II. Obtaining an API key (1/5)

• On the API portal main page (see previous section), click the NanoInformaTIX box.
• You should now see the available subscription plans for the API, with different levels of access and different authentication. Select the “API KEY” plan by clicking on its “SUBSCRIBE” button.
• Make sure to also check the API documentation from the “Documentation” link.

II. Obtaining an API key (2/5)

• The next screen shows the subscription options. Click in the “Select an application...” field and choose “Default application” from the drop-down list.
• The “SUBSCRIBE” button should light up. Click on it.

II. Obtaining an API key (3/5)

• If everything went well, a green notification should appear in the lower right corner.
• Scroll down to find the unique API key that has been issued to you. You can copy it to the clipboard by clicking on the indicated button. Please note that the example provided below the API key may be empty or not working, due to limitations in the current version of the API portal. This will likely be fixed in the future.

II. Obtaining an API key (4/5)

1. You can try the key in the demo notebooks, in section “Aggregated search” of the tutorial.
2. You can also do a quick test with curl, which in the example here is also supplemented by jq:�curl -s "https://api.ideaconsult.net/nanoinformatix/select?q=*:*&rows=1&wt=json" \� -H "X-Gravitee-Api-Key: 01eb454d-a494-4901-a7bb-93c555ba925b" | jq .

II. Obtaining an API key (5/5)

Keep your API key secret!

It gives the same level of access to the data as your password.

III. Retrieving a forgotten API key (1/2)

If you forget your API key, do the following steps to retrieve it:

1. Open https://api.ideaconsult.net and log in if necessary (see “database API access” above 1 & 2).
2. Click on the person icon in the top right corner and choose “Applications” from the menu that will pop up.
3. From the “Applications” screen, choose “Default application”. NB: If you have created different apps, choose the one that you used to subscribe.

III. Retrieving a forgotten API key (2/2)

​

​

​

• From the application screen, click on the key icon on the left.
• Now click on the respective API and the next screen will show your API key.

IV. Configuring OAuth2 (1/2)

• The main supported OAuth2 setup is:
• the client must use the Authorization Code Grant flow
• an allowed redirect URI or a list of such URIs must be provided
• the redirect URI(s) must use https; plain http is not allowed
• redirect URIs with patterns/wildcards are not allowed
• the client may not request other scopes than:
• enanomapper.nanoinformatix.read
• offline_access (if refresh tokens will be employed)
• the access tokens will be valid for:
• 7200 seconds (2 hours) with refresh tokens
• 86400 seconds (24 hours) without refresh tokens
• the refresh tokens will be valid for 604800 seconds (7 days)
• it is expected that the client follows the OAuth 2.0 Security Best Current Practice
• Other setups may be possible on request: please contact support@ideaconsult.net to discuss them.
• The authorization server OAuth2 API documentation is available here: https://docs.gravitee.io/am/2.x/oauth2/
• The authorization server OAuth2 API is exposed at: https://idp.ideaconsult.net/auth/idea-api/oauth

IV. Configuring OAuth2 (2/2)

To have your OAuth2 client registered:

1. Log in to the API portal as described in the section “Accessing the API portal” earlier in this document.
2. Send the following information to support@ideaconsult.net:
1. client description (if not discussed previously)
2. preferred client_id name (the final name will have some random string appended)
3. whether the client will use refresh tokens (and require the offline_access scope)
4. an allowed redirect URI or a list of such allowed redirect URIs
3. After the client is registered and you get back the final client_id and the client_secret, subscribe to the API.

Further support

​

​

If you encounter any problems with these procedures, please contact support@ideaconsult.net.