API User Guide

The ReadSoft Online API (RSO-API) allows partners to access to the services available in ReadSoft Online. The API is an interface between ReadSoft Online and other systems, and it allows integrators to exchange information with ReadSoft Online. The API is exposed by a number of services that allow access and interaction with ReadSoft Online.


The API structureReadSoft Online

This guide describes how to use the ReadSoft Online API. All examples use the European production environment URLs. When using the ReadSoft Online API, the URLs must reflect the correct system. Currently, the following systems are in use.

System URL
European production system https://services.readsoftonline.com
Australian production system https://services-au.readsoftonline.com
North American production system https://services-us.readsoftonline.com

ReadSoft Online consists of an organization level hierarchy and, depending on the needs of the integration, it is important to log in to ReadSoft Online on the appropriate organization level.

It is possible to log in on a Partner and Customer level from the API. The authentication could be done with either a User account or an Administrator account.

The functionality that is available from the API differs depending on the organization level (this is pointed out in the Online API documentation).


Organization Hierarchy

The ReadSoft Online API Reference

The ReadSoft Online API reference is an online service available at the following address:

https://services.readsoftonline.com/documentation/rest

The RSO-API reference is generated from code that is always an accurate description of the API, reflecting the system where the service is located. The reference pages are split up into an overview page containing links for each method call. The online reference contains schemas for all entities and their properties. The whole schema for the entities can be accessed from the following address:

https://services.readsoftonline.com/documentation/rest/xsd

Information in the schemas, such as format or required attribute, is not relevant in the automatically generated API reference.

Note The API is under continuous development, and new elements can be added without warning.

Downloading the SDK and samples

.NET Client SDK

In order to integrate with the ReadSoft Online API, there is a .NET SDK available that could be downloaded as part of the SDK package. The .NET SDK contains a couple of assemblies that should be referenced in the development project (for instance if Visual Studio is used).

When using the SDK, it requires the .NET 4 framework to be installed.

Service Clients

The ReadSoft Online API is divided into different services. Each service can be accessed through wrapper classes (Service Clients) found in the .NET SDK.

For complete documentation about the .NET SDK, download the binaries and use them in a project in Visual Studio. The online documentation contains a subset of the operations that are available in the .NET SDK.

You can download the SDK and samples from the following location:

https://services.readsoftonline.com/documentation/rest/client

The link above prompts you to download a ZIP file which contains the SDK and sample code. Each sample is described in the scenarios.

Need more help?

The developer forum is a great place to post questions and collaborate with fellow developers. Find out more at developer.readsoftonline.com

Version information

The version tag is used to manage different versions of the API. The default value is the first version that is released.

Syntax (required) Example
x-rs-version: <service version> x-rs-version: 2011-10-14

Enables caller to specify service version.

API Key

The key must be included in all calls to the different services. Each sub-domain (selected when an account is created) has its own key.

Syntax (required) Example
x-rs-key: <api key for application> x-rs-key: 30B5C6E9-34B2-4AA1-9920-DBDF95EE3E48

This key is supplied by customer support or through the admin UI.

Culture

Sets the current culture to the supplied language culture if supported or falls back to English.

Syntax (required, must follow RFC1766) Example
x-rs-culture: <culture> x-rs-culture: sv-SE

UI-culture

Sets the current UI-culture to the supplied culture if supported or falls back to English.

Syntax (required, must follow RFC1766) Example
x-rs-uiculture: <culture> x-rs-uiculture: sv-SE

Content type

Defines format of the data entities that is passed to the service.

Syntax (required) Example
Content-Type: <content type> Content-Type: application/soap+xml
  Content-Type: application/xml
  Content-Type: application/json

Accept

The accept value defines the format of the data entities that is passed as a result from the service call.

Syntax (required) Example
Accept:  <content type> Accept: application/soap+xml
  Accept: application/xml
  Accept: application/json

Syntax

The JSON and plain XML interfaces have the following syntax:

https://services.readsoftonline.com/<serviceName>/rest

Schema information for the different entities is published as XML-schemas and can be found at the online reference.

REST authentication

This is a C# example of how to log into ReadSoft Online using the REST API.

class Program
 {
private static Uri authUri = 
 new Uri("https://services.readsoftonline.com/authentication/rest/authenticate");
 
 private static Cookie currentCookie = null;
 
 static void Main(string[] args)
 {
 Authenticate();
 }
 
 private static void Authenticate()
 {
 HttpWebRequest client = (HttpWebRequest)HttpWebRequest.Create(authUri);
 
 client.CookieContainer = new CookieContainer();
 client.Accept = "application/xml";
 client.ContentType = "application/xml";
 client.Headers.Add("x-rs-version", "2011-10-14");
 client.Headers.Add("x-rs-key", "1F6C568B-84DA-43FB-A9CE-80FB4E0B6EFA");
 client.Headers.Add("x-rs-culture", CultureInfo.CurrentCulture.Name);
 client.Headers.Add("x-rs-uiculture", CultureInfo.CurrentUICulture.Name);
 client.Method = "POST";
 
 using (Stream request = client.GetRequestStream())
 {
 using (StreamWriter sr = new StreamWriter(request, Encoding.UTF8))
 {
sr.Write("<AuthenticationCredentials><UserName>account_name</UserName><Password>account_password</Password><AuthenticationType>SetCookie</AuthenticationType></AuthenticationCredentials>");
 }
 }
 
 using (WebResponse response = client.GetResponse())
 {
 using (Stream resp = response.GetResponseStream())
 {
 using (StreamReader sr = new StreamReader(resp, Encoding.UTF8))
 {
 System.Diagnostics.Debug.WriteLine(sr.ReadToEnd());
 }
 }
 }
 
 if (client.CookieContainer.Count > 0)
 {
 currentCookie = client.CookieContainer.GetCookies(authUri)[0];
 }
 }
 }
 

Accessing the ReadSoft Online API

To access the ReadSoft Online API, you must provide an API key upon login. The API key is used for multi-tenancy security and to distinguish each account. You find the API key in Admin Center on the partner level in the Target system view.

Exception handling

Handling exceptions in a proper way is crucial when integrating with ReadSoft Online. These are the most common status codes that the server can return.

HTTP Status Code 400 – Bad request

The server can return this code for example if a request is made to a document or other object that does not exist. If you receive an error code 400, there is no reason to continue with the request since this indicates a defect in client code.

HTTP Status Code 401 – Unauthorized

This code is returned when the requesting user does not have permission to access a method. This can also be returned when the wrong API key is used. If you receive an error code 401, there is no reason to continue with the request since this indicates a defect in client code.

HTTP Status Code 500 – Internal server error

This code is returned if there are any exceptions taking place on server side. When this code is returned, you can make controlled attempts to try again.

Handling exceptions in client-side code

The status codes should be handled in the following way:

HTTP Status Code 4xx

When the server returns any of these error codes (starting with 4xx), log the error locally. Do not request this method again until the exception has been resolved.

HTTP Status Code 5xx

When the server returns any of these error codes (starting with 5xx), you can retry the same method call a maximum 10 times over a time period of 10 hours.

Throttling

Throttling will be introduced in the near future. This means that API access will be limited if the number of retires are not following ReadSoft Online recommendations.

Date and amount formats

The following formats are used in the ReadSoft Online API:

Date format:YYYYMMDD

Amount format:NNNN.NN (dot as decimal separator, no thousand separator)

Note XML data uses the XML standard for dates and amount.

Paging

When retrieving entities that can exist in large quantities, such as batches or documents, the API offers paging to reduce the amount of data retrieved in a single call. When calling an API operation which supports paging using REST, you must include two parameters in the query string: the Page Index and the Page Size. When calling the operation using SOAP, the page index and page size are normal parameters in the operation signature.

Using the page-size parameter, you tell the API how many items you want to retrieve. Using the Page Index parameter, you tell the API which page you want to start retrieving. For example, if there are 10,000 batches in the system and you want to retrieve information for 1,000 batches at a time, you first call the API with page index 0 and page size 1,000. This retrieves the first 1,000 items. After this, call the API with page index 1 and page size 1000. This retrieves the next 1,000 items. Continue like this to retrieve all the batches. If you set the page size to 1,000, but there are only 500 items, only 500 are returned.

API operations that return paged data also return information on the total number of pages in the data (page count). In the above example, the page count would be 10 (10000 / 1000).

Single Sign-On

Single sign-on via the API has been deprecated.

Using the API user guide

The next section describes different scenarios which have sample code that can be downloaded. The code uses the .NET Client SDK, but it can be translated to the REST API by using the online RSO-API documentation.

All code in this user guide uses the .NET Client SDK and is described in C# (except for some illustrations that are specifically noted).

Need more help?

The developer forum is a great place to post questions and collaborate with fellow developers.