C# client SDK for the Exact Online RESTFul API

Dare to contribute

At Exact we know how important it is to have an API you can easily work with. In reaching this ambition the next step is to offer you a C# client SDK which gives you a set of easy functions to call our API. Just some words for otherwise long statements. Combine it with the right Oauth framework and you are quickly on your way.

We have built this open-source client SDK so that you, as part of our community, can contribute to this C# SDK or just build a client SDK for the language you love. Check out the Github page and start contributing to make all our lives more focused.

Quick Guide

The Exact Online Client SDK provides a rich application framework and simplifies the interconnection with the Exact Online RESTful API. The Exact Online API can help you to quickly integrate with Exact Online and build innovative apps within the .NET environment. This document describes how to get started using the Exact Online Client SDK.

The sample code in this document is in C#

1. Reference Libraries

Include following references in your web project:

ExactOnline.Client.Models.dll
ExactOnline.Client.Sdk

Add following namespaces in your code file:

using ExactOnline.Client.Models;
using ExactOnline.Client.Sdk;

2. OAuth

We have added an ExactOnline.Client.OAuth module, which takes care of the authentication. In this way you can easily execute the integration tests and user acceptance tests. When you want to use this you need to fill in your own client ID, client secret and callback url in the ExactOnline.Client.Sdk.TestContext in the TestObjectsCreator class. Of course you also can use your own OAuth implementation.

3. Initializing Exact Client

ExactOnline Client only supports the OAuth authentication for the API calls. To know more about OAuth please refer to Getting started - OAuth. To initialize the ExactOnlineClient object you need to provide the “apiEndPoint” & “AccessTokenDelegate”:

ExactOnlineClient client = new ExactOnlineClient (apiEndPoint, AccessTokenDelegate);

For multiple administrations you can also specify the division

ExactOnlineClient client = 
        new ExactOnlineClient (apiEndPoint, division, AccessTokenDelegate);

apiEndPoint: Exact Online URL for your country. For Netherlands: “https://start.exactonline.nl”

AccessTokenDelegate: Delegate that will be responsible to retrieve and refresh the OAuth access token. For OAuth implementation please refer to Example OAuth.

4. Insert Record Using ExactOnline Client

To insert a record using the ExactOnlineClient instance for a specific entity, you first need to initialize the object for that entity and provide all the required values.

E-g: To insert a new “Document” record, first create a new object for “Document”:

Document document = new Document
		   {
			Subject = "User Acceptance Test Document",
			Body = "User Acceptance Test Document",
			Category = GetCategoryId (client),
			Type = 55, //Miscellaneous
			DocumentDate = DateTime.Now.Date
		   };

Use the ExactOnlineClient instance to insert the record:

bool created = client.For<Document>().Insert(ref document);

“Insert” method takes entity object as reference and returns “true” if the insertion is successful. After successful insertion, the document ID can be retrieved as:

document.ID

5. Retrieve Data Using Exact Client

To retrieve the entity based on ID you can use the “GetEntity” function. E-g: Retrieve document by ID:

client.For<Document>().GetEntity(documentID);

To retrieve specific fields of the entity based on filter use “select” and “where” functions. E-g: Retrieve document with specific fields for subject “User Acceptance Test Document”

var fields = new[] { "ID, Subject, Type, Category" };
var documents = client.For<Document>().Select(fields).Top(5).Where("Subject+eq+'User Acceptance Test Document'").Get();

If “Select(fields)” is not specified you will get an exception. You always need to specify which fields you need, to limit the data traffic. Paging: For paging use “Skip” and “Top” functions

var documents = client.For<Document>().Select(fields).Skip(2).Top(5)
.Where("Subject+eq+'User Acceptance Test Document'").Get();

6. Update Record Using Exact Client

Update the fields in the entity object and pass this object to “Update” function of the ExactOnlineClient instance, which will return “true” if update is successful.

document.Subject = "User Acceptance Test Document Updated";
document.DocumentDate = DateTime.Now.Date;
var updated = client.For<Document>().Update(document);

7. Delete Record

To delete a record you need to provide the entity object to the “Delete” method of the ExactOnlineClient instance, which will return “true” if the operation is successful. ``` var deleted = client.For().Delete(document); ```

8. Exceptions

Exception	Description
UnauthorizedException	When access token is null or invalid while making a request
BadRequestException	When composed request is not in a correct format
ForbiddenException	When some specific operation is not allowed to be performed.
NotFoundException	When trying to retrieve a record which does not exist in the database.
InternalServerError	Please find the validation errors in the error message.

cinamo/exactonline-api-dotnet-client