Opinum API connection

The Opinum API allows for standard data push on a dedicated API using a pre-defined data structure. This option has the advantage not to require the implementation of a dedicated data mapper on the Opinum side but implies that formatting is applied on the client side to match the Opinum standard format.

Opinum also allows for custom data push. The mechanism consists in a standard API POST using a dedicated GUID identifier linked to a custom data mapper to a pre-defined Data Hub data source type.

The API is available on api.opinum.com.

Authentication principles

For the authentication, you will need a client_id and client_secret. You will also need to configure an specific user with Data Pusher access rights.

To push data in a custom format, you will also need a dedicated GUID.

Both the GUID and the client_id/client_secret are provided by Opinum upon request. The user is to be created by a manager of your account.

The Opinum Data Hub structure must exist before the data is sent to our API. Every data sent before the creation of Opinum Data Hub cannot be mapped and will be lost. This structure consists of three elements :

• Site
• Source
• Variable

Request token

The Opinum Authentication mechanism uses the OAuth2 standard.

The bearer token must be requested using :

• The client_secret and client_id provided by Opinum.
• The user credentials

Tip

Contact Opinum support to request your client_secret and client_id at support@opinum.com.

This bearer token will be used in every call to the API.

Note that every call also needs the scope information to provide access to the right feature of the API: It is as such mandatory to add in the header of you call, the following information: scope=["datahub-api","push-data"]

• datahub-api = access to the API (api.opinum.com)
• push-data = access to the push endpoint (push.opinum.com)

The token url is https://identity.opinum.com/connect/token

Here is a code sample to request this token in a .NET environment, in C#

private async Task<string> GetBearerToken()
{
    var scopes = new[] {"datahub-api", "push-data"};
    var response = await new TokenClient($"{IdentityServer}connect/token", ClientId, ClientSecret)
        .RequestResourceOwnerPasswordAsync(Username, Password, string.Join(" ", scopes));
    if (response.IsError)
    {
        throw new Exception(response.Error);
    }
    StoreRefreshTokenForLaterUse(response.RefreshToken);
    return response.AccessToken;
}

And another example in Python 3.x using OAuthlib and Requests-OAuthlib packages:

from oauthlib.oauth2 import LegacyApplicationClient
from requests_oauthlib import OAuth2Session

def get_datahub_token(datahub_username: str, datahub_password: str):
    """" Get token from DataHub API """
    datahub_client = LegacyApplicationClient(client_id="your_client_id")
    oauth = OAuth2Session(client=datahub_client)
    datahub_token = oauth.fetch_token(token_url="https://identity.opinum.com/connect/token",
                                       client_secret="your_client_secret",
                                       scope=["datahub-api","push-data"],
                                       username=datahub_username,
                                       password=datahub_password,
                                       client_id="your_client_id")
    return "Bearer " + datahub_token["access_token"]

Data push principles

There is two ways to push data through Opinum API :

1. Using the standard: you map the data to make it fit in Opinum standard format
2. Using a custom format: you push you raw data and the mapping is made by Opinum

Tip

Learn more about the standard format

Tip

Learn more about the custom format

Test the API with Swagger

You can visualize and interact with the API thanks to Swagger UI.

• Login to Data Hub with the user that will use the API
• Go on Opinum Swagger UI.
• Click on the button Authorize at the right of the page.

• The connection pop-up opens. Check the check box datahub-api and click on the Authorize button.

• The confirmation pop-up opens. Click on the Close button.

• You are now connected to Swagger and can enjoy the Opinum API.

• To log out, click on the Authorize button again, the connection pop-up opens. Then click on the Logout button.

Tip

Learn more about every entry points of the API.