Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents


Authenticating


Most routes will require authentication. This is performed by invoking the /auth route and passing the username and password of a Jiwa user.  A successful authentication will return an authentication response containing the SessionId.  All subsequent requests will need to provide the SessionId as the value for the cookie "ss-id".

Panel
titleAuthenticate by calling the /auth route


Deck
idauthenticate


Card
idauthenticate_ss_csharp
labelServiceStack Client C#

See Installing the ServiceStackVS Extension for Visual Studio on how to configure your Visual Studio project to use the ServiceStack client needed for this example.

Code Block
languagec#
var client = new ServiceStack.JsonServiceClient("https://api.jiwa.com.au");
var authResponse = client.Get(new ServiceStack.Authenticate() { UserName = "admin", Password = "password" });


Card
idauthenticate_csharp
labelC#

Code Block
languagec#
using (var webClient = new System.Net.WebClient())
{
    // Authenticate               
    webClient.QueryString.Add("username", "Admin");
    webClient.QueryString.Add("password", "password");
     
    string responsebody = webClient.DownloadString("https://api.jiwa.com.au/auth");               
}


Card
idauthenticate_bash
labelCurl

Code Block
languagebash
curl -H 'Accept: application/json' -H 'Content-Type: application/json' -X GET https://api.jiwa.com.au/auth -d '{"username":"Admin","password":"password"}'


Card
idauthenticate_browser
labelWeb Browser

Navigate to the auth URL and provide the username and password as parameters:

No Format
https://api.jiwa.com.au/auth?username=admin&password=password&format=json

This authenticates the user and creates a cookie, so a subsequent request will automatically include the SessionId. Note the &format=json in the above URL this overrides the content type returned. For browsers the default content type is HTML - if a content type override is omitted, then a HTML razor view of the data will be returned instead of json. xml and csv are also valid overrides for the content type to be returned. We only used ?format=json in this example to demonstrate the return value.



The response returned from the above request:

No Format
{"SessionId":"6w1nLX8r0sIrJHClX9Vj","UserName":"Admin","DisplayName":"","ResponseStatus":{}}
Calling




Example of calling a route

Code Block
languagec#
titleUsing ServiceStack.Client
// Add "using JiwaFinancials.Jiwa.JiwaServiceModel;" to your code to import the namespace required for debtorGETResponse and DebtorGETRequest   // Authenticate

Once authenticated,

Panel
titleRetreiving a debtor record from the /Debtors/\{DebtorID\} route


Deck
idretrieve_debtor


Card
iddebtor_ss_csharp
labelServiceStack Client C#

See Installing the ServiceStackVS Extension for Visual Studio on how to configure your Visual Studio project to use the ServiceStack client needed for this example.

Code Block
languagec#
var client = new ServiceStack.JsonServiceClient("
http
https://api.jiwa.com.au");
var authResponse = client.
Send<ServiceStack.AuthenticateResponse>
Get(new ServiceStack.Authenticate() { 
provider = "credentials",
UserName = "
api
admin", 
Password = "password"
, RememberMe = true
 });
// Read

a

debtor

var debtorGETResponse = client.Get(new DebtorGETRequest { DebtorID = "0000000061000000001V" });

 

Using the .NET WebClient

  • Add References to System.Runtime.Serialization and System.Net
  • Add the nuget package Newtonsoft.Json
  • 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:
    Image Removed
  • Create a cookie aware WebClient using this code - this is needed to send the session Id with every request:

    Code Block
    languagec#
    titleCookie 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;
    	}
    }

    Add the following code:

    Code Block
    languagec#
    titleUsing WebClient
    using (var webclient = new CookieAwareWebClient(


    Card
    iddebtor_csharp
    labelC#

    Code Block
    languagec#
    using (var webClient = new System.Net.WebClient())
    {
        // Authenticate               
     
       webClient.QueryString.Add("username", "
    api
    Admin");
       
     webClient.QueryString.Add("password", "password");
    
         
        string responsebody = 
    webclient
    webClient.DownloadString("
    http
    https://api.jiwa.com.au/auth");
        // Deserialise response into a dynamic - below requires the Newtonsoft.Json nuget package - or you can use any other json serialisation library
    	
    ServiceStack.AuthenticateResponse
    var 
    webClientAuthResponse
    authResponse = Newtonsoft.Json.JsonConvert.
    DeserializeObject<ServiceStack.AuthenticateResponse>
    DeserializeObject<dynamic>(responsebody);
    	var 
    // Read a debtor
    sessionId = authResponse.SessionId;
    
    	webClient.Headers.Add(System.Net.HttpRequestHeader.Cookie, string.Format("ss-id={0}", sessionId));                
    	responsebody = 
    webclient
    webClient.DownloadString("
    http
    https://api.jiwa.com.au
    :80
    /
    debtor
    Debtors/0000000061000000001V");         
    }


    Card
    iddebtor_bash
    labelCurl

    Code Block
    languagebash
    curl -H 'Accept: application/json' -H 'Content-Type: application/json' -X 
    JiwaFinancials.Jiwa.JiwaServiceModel.DebtorGetResponse webClientDebtorGetResponse = Newtonsoft.Json.JsonConvert.DeserializeObject<JiwaFinancials.Jiwa.JiwaServiceModel.DebtorGetResponse>(responsebody); }

     

     
    GET https://api.jiwa.com.au/auth -d '{"username":"Admin","password":"password"}'
    curl -H 'Accept: application/json' -H 'Content-Type: application/json' -X GET https://api.jiwa.com.au/Debtors/0000000061000000001V -d '{"username":"Admin","password":"password"}'


    Card
    iddebtor_browser
    labelWeb Browser

    Navigate to the auth URL and provide the username and password as parameters:

    No Format
    https://api.jiwa.com.au/auth?username=admin&password=password&format=json



    The response returned from the above request:

    No Format
    {"SessionId":"6w1nLX8r0sIrJHClX9Vj","UserName":"Admin","DisplayName":"","ResponseStatus":{}}






    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.

    Code Block
    languagec#
    titleUsing WebClient Manually and with no dependencies
    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.

    Code Block
    languagec#
    titlestateful requests
    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" });
    }

     

    When the server creates the business logic object, it is stored in a collection associated with the users session (this is actually a property of the Manager class - the ObjectDictionary).  Subsequent stateful requests for the same type (eg: Debtor Maintenance operations) will retrieve any existing business logic for the same record, otherwise a new business logic instance is created.

    This means two subsequent stateful operations for different debtors will result in two business logic objects created by the server, and they will remain independent of each other.

    Conversely, two subsequent stateful operations for the same debtor will result only one business logic object created by the server, and the second operation will be working on the same business logic instance as the first operation.

     

    Filter by label (Content by label)
    showLabelsfalse
    max5
    spacesAPI
    showSpacefalse
    sortmodified
    reversetrue
    typepage
    cqllabel in ("consume","c-sharp","restapi") and type = "page" and space = "J7UG"
    labelsconsume c-sharp

    Page Properties
    hiddentrue


    Related issues