How to use Sidra API¶

This document provides a guide about how to use Sidra API. The API surface is organized in groups that provides endpoints that are related between them. Samples of the most common groups are:

• Metadata group: contains endpoints to implement CRUD operations over metadata -Providers, Entities, Attributes, etc.-.
• Ingestion group: contains endpoints to provide Asset ingestion into the platform.

Sidra API is in continuous improvement, so the endpoints could change along time. For more information about the specifics of the Sidra API endpoints, a Swagger documentation is deployed with every Sidra API and it can be accessed from the base url where Sidra API is deployed.

The base URL depends on the specifics of the installation, the environment and the naming conventions. Sidra API is deployed in an Azure App service instance and the default naming is:

https://core-<<name of the installation>>-<<environment>>-wst-api.azurewebsites.net

For example:

https://core-mycompany-dev-wst-api.azurewebsites.net

It is possible that there are two Azure App Service created in the same resource group; this is because one is for Sidra API (the one that ends with -api) and the other is for Web frontend application (the one that ends with -frontend). This document focuses on the Sidra API, not the Web frontend.

Sidra API provides a set of methods with Metadata and it is used by consuming applications to synchronize the content from Sidra Service. In addition, this API provides methods to upload files and to perform operations with the Storage (currently under development*)

Authentication¶

Sidra API can be accessed by a default OAuth protocol, using an Access Token provided by Microsoft Entra ID (Azure Active Directory before). The AAD applications used for this purpose are created during the initial setup of the environment. Sidra API is accessible from the following ways:

• Using a Native application which has the right permissions to access to the API. This is the recommended way, as it will include the user information.
• Using a clientId/clientSecret authentication. This is another way, used internally at the moment between Sidra and consuming applications.

The code example in next sections explain how to get the token in C#.

Authentication code examples in C#¶

There is a NuGet package that could be installed to provide some support in authentication operations. This package is:

Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory

Once the package is installed, the following methods can be used to retrieve the Access Token. The access token should be added later in the request to the API as the content of the "Authentication" header, as a bearer token.

This is an example of how to retrieve an access token from AAD using a popup:

public string GetToken()
{
    string clientID = "{THE NATIVE APPLICATION ID}";
    string redirectUrl = "https://login.live.com/oauth20_desktop.srf";
    string resourceUrl = "{THE RESOURCE URL TO ACCESS}";
    string authorityUrl = "{YOUR AUTH2 AUTHORITY URL}";

    AuthenticationContext authContext = new AuthenticationContext(authorityUrl);
    string token = authContext.AcquireToken(resourceUrl, clientID, new Uri(redirectUrl)).AccessToken;

    return token;
}

The parameters required to execute the requests are:

• clientID: The native applicationID created during Setup phase to support this.
• resourceUrl: The resource to get. This is the IdentifierUrl of the web App/API AAD application associated with API.
• authorityUrl: The authority URL endpoint from the Microsoft Entra ID associated with the applications. It will have the format https://login.microsoftonline.com/{TENANT_ID}/oauth2/authorize

With this approach, a popup will be opened in AcquireToken method to put your credentials. That popup is provided by the AAD itself, so it is the same than login using a website or accessing to the Azure Portal as an example.

First time that you log in, it will ask your permission to access to the application configured in AAD. Just confirm it and allow all the permissions requested; otherwise there will be issues accessing the resources.

There is another workflow to login without popup. Note with that is strongly recommended using a service account and not your personal account, as the password will appear in the code:

public string GetAccessToken()
{
    string clientID = "{THE NATIVE APPLICATION ID}";
    string resourceUrl = "{THE RESOURCE URL TO ACCESS}";
    string authorityUrl = "{YOUR AUTH2 AUTHORITY URL}";

    string username = "{USERNAME}";
    string password = "{PASSWORD}";

    AuthenticationContext context = new AuthenticationContext(authorityUrl);

    var token = context.AcquireTokenAsync(resourceUrl, clientID, new UserPasswordCredential(username, password)).Result;

    return token.AccessToken;
}

Parameters clientID, resourceUrl and authorityUrl are the same as those in the "popup" example. Username and password are the ones of the account to connect. This account should have access to the AAD where the applications have been created.

{AUTHORITY_URL}/oauth2/authorize?resource={RESOURCE_URL}&client_id={CLIENT_ID}&response_type=code&redirect_uri=https://login.live.com/oauth20_desktop.srf