com.hyperscience.saas 1.0.14

Hyperscience SaaS Client Library

With the Hyperscience SaaS client library, you can authenticate to SaaS instances of Hyperscience and make API requests. The library supports the following frameworks:

• .NET Framework 4.6.1 or above
• .NET and .NET Core 2.0 or above

Quickstart Guide

1. Set up API credentials

Retrieve your API credentials from your Hyperscience SaaS instance. To learn more, see API Access for SaaS Instances.

2. Configure authentication parameters

You can configure the authentication parameters using the ApiController. The ApiController uses a Configuration object. This object includes data about the following:

• Hyperscience's domain to make the requests to (hs_domain) - mandatory
• Authentication domain (auth_server) - optional, defaults to login.hyperscience.net
• Timeout configuration in seconds (timeout_configuration) - optional, defaults to connection_timeout: 60 and read_timeout: 60

This is a JSON example for the configuration (you should set the hs_domain value):

{
   "hs_domain": "hs_instance.hyperscience.net",
   "auth_server": "login.hyperscience.net",
   "timeout_configuration": {
     "connection_timeout": 60,
     "read_timeout": 60
   }
}

You can set your Configuration object in one of the following three ways.

From a JSON string

string jsonString = $@"
   {{
      ""auth_server"" : ""login.hyperscience.net"",
      ""hs_domain"" : ""tpi-dev.hyperscience.net"",
      ""request_timeout_in_seconds"" : 180
   }}";
var configuration = Hyperscience.Saas.Config.Configuration.FromJsonString(jsonString);

From a JSON file

var configuration = Hyperscience.Saas.Config.Configuration.FromJsonFile("/full/path/to/Config.json");

At object instantiation

var configuration = new Hyperscience.Saas.Config.Configuration("<Hyperscience_URL>");
// or
var configuration = new Hyperscience.Saas.Config.Configuration("<Hyperscience_URL>", "login.hyperscience.net");

3. Provide Credentials

There are two options for providing credentials:

a. Environment Variables (Recommended)

To use environment variables to store your credentials, follow the steps below:

• Put your client_id in an .env file variable called HS_CLIENT_ID.
• Put the client_secret in an .env file variable called HS_CLIENT_SECRET.

Then, these credentials will be loaded from environment variables if the ApiController class is instantiated as:

var configuration = new Configuration("<Hyperscience_URL>");
//Implicitly
var apiController = new ApiController(configuration);
//Or Explicitly
var apiController = new ApiController(configuration, new EnvironmentCredentialsProvider());

b. In code using an instance of CredentialsProvider

var credentials = new CredentialsProvider("<clientid>", "<clientsecret>");
var apiController = new ApiController(configuration, credentials);

We strongly recommend against storing your credentials in code. Instead, we recommended calling out to an external, secure service to fill in the client_id and client_secret variables.

4. Make a Test Call

Ensure that your setup is correct by making a test call to GET submissions from your instance.

var configuration = new Configuration("<Hyperscience_URL>");
CredentialsBase credentials = new CredentialsProvider("<client_id>", "<client_secret>");
ApiController _apiController = new ApiController(configuration, credentials);
var httpResponseMessage = _apiController.Get("/api/v5/submissions");
Console.WriteLine(httpResponseMessage.ToString());
Console.WriteLine(httpResponseMessage.Content.ReadAsStringAsync().Result);

Using the ApiController

The ApiController allows users to interact with the Hyperscience API by utilizing wrapper methods. To learn more, see Hyperscience’s API documentation.

Supported Methods

The ApiController supports GET, POST, and PUT operations, with both synchronous and asynchronous versions of them.

Synchronous functions return a HttpResponseMessage and are named:

• Get
• Post
• Put

Asynchronous functions return a Task<HttpResponseMessage> and are named:

• GetAsync
• PostAsync
• PutAsync

You can find more information about asynchronous execution here.

Parameters for these operations (query params, encoded url parameters, or files input) can be provided by a Collection that implements IEnumarable<KeyValuePair<string, string>>`. You can use either one of the approaches below:

• Dictionary<string, string> - if duplicate keys are not needed
• List<KeyValuePair<string, string>> - if duplicate keys are needed

Examples

Configuration and Setup

using System.Net.Http;
using Hyperscience.Saas.Config;
using Hyperscience.Saas.Service.Api;
using Hyperscience.Saas.Service.Api.Enum;
using Hyperscience.Saas.Service.Auth.Model.Credentials;

var configuration = new Configuration("<Hyperscience_URL>");
var credentials = new Credentials("<clientid>", "<clientsecret>");
var apiController = new ApiController(configuration, credentials);

GET Submissions

var httpResponseMessage = _apiController.Get("/api/v5/submissions");
Console.WriteLine(httpResponseMessage.ToString());
Console.WriteLine(httpResponseMessage.Content.ReadAsStringAsync().Result);

POST a New Submission Using UrlEncoded Content Type

var duplicateKeysAllowed = new List<KeyValuePair<string, string>>();
duplicateKeysAllowed.Add(new KeyValuePair<string, string>("file", "s3://path/to/file.jpg"));
duplicateKeysAllowed.Add(new KeyValuePair<string, string>("file", "https://host/path/to/file2.jpg"));

// If no payload type is passed, it defaults to DataSupportedContentType.UrlEncoded
var httpResponseMessage = apiController.Post(
    "/api/v5/submissions", duplicateKeysAllowed
);

// Or explicitely defining the payload as DataSupportedContentType.UrlEncoded
httpResponseMessage = apiController.Post(
    "/api/v5/submissions", duplicateKeysAllowed, DataSupportedContentType.UrlEncoded
 );

POST a New Submission Using MultipartFormData Content Type

var filesDictionary = new Dictionary<string, string>();
filesDictionary.Add("file", "/absolute/path/to/file/demo-long.pdf");

var httpResponseMessage = apiController.Post(
    "/api/v5/submissions", filesDictionary, DataSupportedContentType.MultipartFormData
 );

POST a New Submission Using ApplicationJSON Content Type

Although the general recommendation is to use MultipartFormData as content type because it is possible to send large documents if needed, JSON payloads are also supported by Hyperscience's API. Details about the format of the payload can be found in Hyperscience's API documentation.

Given the following JSON file:

{
  "metadata": null,
  "machine_only": true,
  "goal_duration_minutes": 5,
  "single_document_per_page": true,
  "restrictions": [],
  "source_routing_tags": [
    "tag1",
    "tag2"
  ],
  "files": [
    {
      "file_content_base64": "data:image/png;base64,iVBORw0KGgA ... <base64encodedFile> ... CYII=",
      "filename": "image.png"
    }
  ],
  "cases": [
    {
      "external_case_id": "case_1",
      "filenames": [
        "image.png"
      ]
    }
  ]
}

Load the file into memory and send it as a dictionary:

string jsonContent = System.IO.File.ReadAllText(@"<file_path>");
dynamic jsonObject = JsonConvert.DeserializeObject<Dictionary<string, object>>(jsonContent);
var httpResponseMessage = _apiController.Post(
  "/api/v5/submissions", jsonObject, PayloadSupportedContentType.ApplicationJson
);

Obtaining Response's Content

Regardless whether the request is made synchronously or asynchronously, obtaining HttpResponseMessage's content as a string requires calling ReadAsStringAsync, which returns a Task<string> object.

Console.WriteLine(httpResponseMessage.Content.ReadAsStringAsync().Result);

Logging

The Hyperscience SaaS client library uses Serilog for logging purposes. To learn more about Serilog, see the Serilog.Settings.Configuration documentation on the GitHub website.

The library comes with a default configuration that has the log level setting set to “Information”. To override this setting, add the appsetting.json configuration file to your project. In your IDE, make sure to set the Copy to output directory setting to “Always”.

Sample appsetting.json configuration file

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  },
  "Serilog": {
    "Using":  [ "Serilog.Sinks.Console", "Serilog.Sinks.File" ],
    "MinimumLevel": "Debug",
    "WriteTo": [
      { "Name": "Console" },
      { "Name": "File", "Args": { "path": "Logs/log.txt" } }
    ],
    "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ],
    "Destructure": [
      { "Name": "ToMaximumDepth", "Args": { "maximumDestructuringDepth": 4 } },
      { "Name": "ToMaximumStringLength", "Args": { "maximumStringLength": 100 } },
      { "Name": "ToMaximumCollectionCount", "Args": { "maximumCollectionCount": 10 } }
    ],
    "Properties": {
      "Application": "Sample"
    }
  }
}