Consuming the REST API using C-Sharp

When writing clients in C# to consume the API, You can use the ServiceStack client (easy way) or use the .NET web client (harder way).

Using the ServiceStack Client

1. Install the ServiceStackVS extension
2. Add the nuget package ServiceStack.Client
3. Add References to System.Runtime.Serialization and System.Net
4. Right-click on the project and choose "Add ServiceStack Reference..."
   
5. Enter the address of the host and name the service
   

6. Add the following Code:

   Using ServiceStack.Client

   // Add "using JiwaFinancials.Jiwa.JiwaServiceModel;" to your code to import the namespace required for debtorGETResponse and DebtorGETRequest
    
   // Authenticate
   var client = new ServiceStack.JsonServiceClient("http://api.jiwa.com.au");
   var authResponse = client.Send<ServiceStack.AuthenticateResponse>(new ServiceStack.Authenticate()
   {
   	provider = "credentials",
   	UserName = "api",
   	Password = "password",
   	RememberMe = true
   });
   
   // Read a debtor
   var debtorGETResponse = client.Get(new DebtorGETRequest { DebtorID = "0000000061000000001V" });

Using the .NET WebClient

1. Add References to System.Runtime.Serialization and System.Net
2. Add the nuget package Newtonsoft.Json
3. Add a new class file to the project and paste the code from the code generator of the API - you can get this by clicking on the "Generate C#" link on the metadata page:
   

4. Create a cookie aware WebClient using this code - this is needed to send the session Id with every request:

   Cookie Aware WebClient

   public class CookieAwareWebClient : WebClient
   {
   	public CookieAwareWebClient()
   	{
   		CookieContainer = new CookieContainer();
   	}
   	public CookieContainer CookieContainer { get; private set; }
   
   	protected override WebRequest GetWebRequest(Uri address)
   	{
   		var request = (HttpWebRequest)base.GetWebRequest(address);
   		request.CookieContainer = CookieContainer;
   		return request;
   	}
   }

5. Add the following code:

   Using WebClient

   using (var webclient = new CookieAwareWebClient())
   {
       // Authenticate                
   	webClient.QueryString.Add("username", "api");
   	webClient.QueryString.Add("password", "password");
   	string responsebody = webclient.DownloadString("http://api.jiwa.com.au/auth");
   
   	ServiceStack.AuthenticateResponse webClientAuthResponse = Newtonsoft.Json.JsonConvert.DeserializeObject<ServiceStack.AuthenticateResponse>(responsebody);
   
   	// Read a debtor
   	responsebody = webclient.DownloadString("http://api.jiwa.com.au:80/debtor/0000000061000000001V");                
   	JiwaFinancials.Jiwa.JiwaServiceModel.DebtorGetResponse webClientDebtorGetResponse = Newtonsoft.Json.JsonConvert.DeserializeObject<JiwaFinancials.Jiwa.JiwaServiceModel.DebtorGetResponse>(responsebody);
   }

Dependency-Free

You can, of course, also consume the REST API without any strong typing or reference to our DTO classes.

Below is a code sample showing how to consume the REST API to logon and retrieve a debtor record with nothing more than a reference to the Newtonsoft.Json nuget package for deserialisation.  This sample also uses the .NET WebClient, but manually sets the SessionId cookie.

using (var webClient = new System.Net.WebClient())
{
	// Authenticate                
	webClient.QueryString.Add("username", "api");
	webClient.QueryString.Add("password", "password");
	
	string responsebody = webClient.DownloadString("http://localhost/auth");                
	// Above returns something like this: {"SessionId":"0hKBFAnutUk8Mw6YY6DN","UserName":"api","DisplayName":"","ResponseStatus":{}}

	// Deserialise response into a dynamic - below requires the Newtonsoft.Json nuget package
	var authResponse = Newtonsoft.Json.JsonConvert.DeserializeObject<dynamic>(responsebody);
	var sessionId = authResponse.SessionId;

	webClient.Headers.Add(System.Net.HttpRequestHeader.Cookie, string.Format("ss-id={0}", sessionId));                
	responsebody = webClient.DownloadString("http://localhost/Debtors/0000000061000000001V");
}

Stateful Interaction

While typically interactions with a REST API would be stateless, it is possible to interact in a stateful way by passing the Request header "jiwa-stateful" with the value of "true".

When stateful requests are received, the server caches the appropriate business logic and subsequent requests will interact with that in-memory object.  This allows the consumer to perform actions like building a sales order without it being saved to the database until it is ready to save it.

Stateful requests will be committed to the database when a SAVE Request is received.  Pending changes can also be discarded with an ABANDON Request.

Below is an example of a stateful interaction with the Debtors - the object is statefully retrieved, and updated until a SAVE Request is sent.

var client = new ServiceStack.JsonServiceClient("http://localhost");
	var authResponse = client.Send<ServiceStack.AuthenticateResponse>(new ServiceStack.Authenticate()
	{
		provider = "credentials",
		UserName = "api",
		Password = "password",
		RememberMe = true
	});

	// Read a debtor
	client.Headers.Add("jiwa-stateful", "true");
	var debtorGETResponse = client.Get(new DebtorGETRequest { DebtorID = "0000000061000000001V" });

	// Update debtor 
	var debtorPATCHResponse  = client.Patch(new DebtorPATCHRequest() { DebtorID = "0000000061000000001V",  Name = "My new name", CreditLimit = 1000 });
 
    // Update some more fields
	debtorPATCHResponse  = client.Patch(new DebtorPATCHRequest() { DebtorID = "0000000061000000001V",  Address1 = "SE2L10 100 Walker Street" });

	// Save the changes
	var debtorSAVEResponse = client.Get(new DebtorSAVERequest() { DebtorID = "0000000061000000001V" });
}

Related articles

• Page:
  REST API
• Page:
  Running the Jiwa API windows service multiple times on the same machine
• Page:
  Adding Custom Routes to the REST API
• Page:
  Open API Specification
• Page:
  Consuming the REST API