Loading...

API Developer Resources

The Wisenet REST API

The REST API is the programming interface to Wisenet. It enables developers to access some of the core information in Wisenet including students, courses, and enrolments. If you’re building an application that uses core Wisenet data, then this is the API for you. In addition to offering programmatic access to the student, course, unit and enrolment objects, this API also enables developers a multitude of integration opportunities to interact with Wisenet.

HTTP and HTTPS

The Wisenet REST API is served over HTTPS. To ensure data privacy unencrypted HTTP is not supported.

Wisenet now only supports TLS 1.2 as of 1st July 2018.

Endpoints

We designed the Wisenet API in a RESTful way, so that your consumption of it is simple and straightforward.

All the data objects in Wisenet (students, courses, enrolments, etc.) are “Resources” in the Web sense: that is to say, they are identified by URIs, and operated on by HTTP requests, chiefly GET and POST. Whenever you GET one of these resources, you receive a representation encoded using XML or JSON.

This documentation should make it obvious that the API interface doesn’t constrain the design of the URI space. URIs used for retrieving, creating, and controlling the resources are provided by the system; clients can make no assumptions as to their internal syntax. URIs may change at any time, but link relations may only change with the release of a new major version of the API.

If you’re looking for more information about RESTful web services, the O’Reilly RESTful Web Services book is excellent.

List of currently available endpoints:

API Entity Relationships

There are many Dropdown lists in Wisenet. Some are static and others are custom defined.

  • A number of the custom Dropdowns are available in the References Endpoint
  • The list values for the other Dropdowns are available in that latest version API Dropdown List Values v6
    • V6 has slight changes to some options in Country and Language

Client Tools

We recommend that you use a test API client like the Chrome plugin Postman. It allows you to quickly test API connectivity and validate how each endpoint works prior to replicating.

https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en

You will need to ensure that you setup the correct headers:

  • Authorization
  • Accept eg. application/xml
  • Conent-Type eg. application/xml

Please see the Postman page with sample call to the Student endpoint by clicking on the image

The cURL utility (http://curl.haxx.se/) is used in this documentation to illustrate usage of API and expected results in a programming-language-neutral way. cURL is available for many platforms and provides a very lightweight way to explore the WiseNET API.

Synopsis of cURL:

 curl [options] [URL]
   '-H' option sets required request headers.
   '-X [command]' option sets command.
   '-v' option sets verbose mode.
   '-d [data]' option sets source datapacket. or
   '-d @[datafilename]' option sets source datapacket from file.
   '-u [username]:[password]' option specifies username and password for basic authorisation

Base URI

All URIs referenced in this documentation have the following base:

https://[YourOrganisationCode]-api.wisenet.co

where [YourOrganisationCode] is the unique three-letter code of your database. (This is the first 3 characters of your Wisenet student ID numbers/ Client RefInternal Numbers. E.g. if your students have numbers like STZ00001R then your code is STZ)

NOTE: There used to be a “play” URI however this has now been retired and any testing should be done on a separate test Wisenet account which will differ by “OrganisationCode”

In true RESTful style, it is our hope that through querying the base URI, a developer getting started with our API will be able to reach and manipulate our APIs without reading through multiple pages of documentation. Your client code must not make assumptions about the URIs of any endpoints, and should only use URIs taken from actual API responses.

Authorisation

All requests to Wisenet’s REST API require you to authenticate using HTTP Basic Authentication (RFC 2617) via SSL to convey your identity. You must provide the username and password of a valid Wisenet user account with Wisenet LRM access.

Important: It is best if you create a user account specific for the integration. This user only needs Wisenet LRM User access for the API to work. If you are providing access to a 3rd Party we recommend that you create the user account and then provide the username/password as this allows you to own the account.

Also you can check Client Side for an example.

Sample request:

 curl -X GET \
   -u user:password \
   -v \
   https://tst-api.wisenet.co/students/student/36521

Sample response:

* Server auth using Basic with user 'user'
> GET /students/student/36521 HTTP/1.1
> Authorization: Basic dXNlcjpwYXNzd29yZA==
> User-Agent: curl/7.19.3 (i386-pc-win32) libcurl/7.19.3 OpenSSL/0.9.8j
> Accept: */*
>
< HTTP/1.1 404 Not Found
< Content-Length: 1245
< Content-Type: text/html
< Server: Microsoft-IIS/7.5
< X-Powered-By: ASP.NET
< Date: Fri, 15 Jul 2011 00:59:20 GMT

C# Code Sample

To use basic authorisation in an HTTP request you need to send the Authorization header with a username:password as a Base64 encoded string. For example:

    var request = HttpWebRequest.Create(url) as HttpWebRequest;
    ...
    // Authorization
    var credentials = String.Format("{0}:{1}", userName, userPassword);
    byte[] credentialBytes = ASCIIEncoding.ASCII.GetBytes(userNameAndPassword);
    var base64EncodedCredentials = Convert.ToBase64String(credentialBytes);

    var authorizationHeader = String.Format("Authorization: Basic {0}", base64EncodedCredentials);
    request.Headers.Add(authorizationHeader);

Sample Code

There is a set of samples in C# provided in /Students endpoint documentation

API Changes and Versioning

The WiseNET API is designed to support both current and previous versions.

The current version of the API is v1.
You specify it by including one of the following vendor specific MIME types in the Accept header of your HTTP request:

application/vnd.mywisenet.api.v1+json
application/vnd.mywisenet.api.v1+xml

When we are about to release next version of API we will notify you and you will be able to test it in the Accept header:

application/vnd.mywisenet.api.v2+json
application/vnd.mywisenet.api.v2+xml

For some time we will support both versions but after a reasonable transition period we will remove support of the previous version (in our example v1).

If above doesn’t work for you try to use the latest version:

application/json
application/xml

Developers should expect that new elements could be added to the XML document or the JSON data structure over time. If any data structures are removed or rearranged, we will release a new version of the API.

We may add additional functionality to the current version of the API but we will not make ‘breaking’ changes to it.

Developers should anticipate the ordering of items within the data structures may change at any time and code appropriately.

Usage Limits

There are usage limits for API calls which Wisenet monitors. This is to protect Wisenet from abuse or excessive load.

The limit is: 1000 calls per 24 hour sliding window per organisation.

Please contact us if you have concerns regarding this.

Retrieving and Sending resources

GET command

You can retrieve a representation of a resource by sending a GET request to its URI. For examples see the Data Formats topic below.

Paging with Skip and Take

The API is designed to limit returned data to 1000 records. If you have more records than this you will need to implement paging. This is achieved by using Skip and Take parameters. The following example is how paging works for the Student endpoint.

GET /students/?skip={skip}&take={take}

Skips {skip} items in student list, then returns {take} items.

Sample request:

 curl -X GET \
   -H "Accept: application/vnd.mywisenet.api.v1+xml" \
   https://tst-api.wisenet.co/students/?skip=100&take=20

You can iterate through pages by adding the {take} value to the {skip} value until the received row count returned is less than the {take} value. Then you know there are no more records to take.

POST command

Adds a new resource to the specified collection.

The Location header on the response includes the canonical URI of the newly created resource.

Sample request:

 curl -X POST \
   -u user:password \
   -H "Content-Type: application/xml" \
   -d @Student2.xml \
   -v \
   https://tst-api.wisenet.co/Students

Sample response:

< HTTP/1.1 200 OK
< Date: Mon, 04 Jul 2011 23:34:04 GMT
< Content-Length: 0
< Location: https://tst-api.wisenet.co/Students/Student/2

PUT command

Updates an existing resource.

Sample request:

 curl -X PUT \
   -u user:password \
   -H "Content-Type: application/xml" \
   -d @Student3.xml \
   -v \
   https://tst-api.wisenet.co/Students/Student/3

Sample response:

< HTTP/1.1 200 OK
< Date: Mon, 04 Jul 2011 23:34:04 GMT
< Content-Length: 0

OPTIONS command

Returns the list of available commands on an endpoint.

Sample request:

 curl -X OPTIONS \
   -u user:password \
   -v \
   https://tst-api.wisenet.co/Students/

Sample response:

< HTTP/1.1 200 OK
< Allow: GET, POST
< Date: Mon, 04 Jul 2011 23:34:04 GMT
< Content-Length: 0

 

Validation and Error handling

Validation

All the fields must be of a proper type and comply with validation rules:

  • If they are alphanumeric they must not exceed some length restriction (usually specified in brackets in an endpoint page-object properties).
  • If field type is not specified than assume it’s alphanumeric.
  • For Bit fields the value can be ‘true’ or ‘false’
  • For Date field in JSON format please see for details

If the field does not comply with the rules API would return 400 code and error description in the body. But it could also return 500. If you come across such a behaviour please lodge the support request so Wisenet would fix this.

Code & Description values

Some object have Code and Description pair as one or more of their properties.

  • When adding or updating such objects you can specify only one of Code or Description, or both.
  • When you have specified both, API will search by Code.
  • For Countries fields if you specify Description only, the partial case-insensitive search in the reference will be done.

i.e. when you send tags

 <Country><Description>AUSTRALI</Description></Country>

the Country: Australia and external territories can be saved in the property.

Error handling – HTTP codes

If a request fails, the error information is returned with the HTTP status code. Depending on operation you are performing the following error codes can be returned:

 

If Wisenet is having trouble, you might see a 5xx error. 500 means that the app is entirely down, but you might also see 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout. It’s your responsibility in all of these cases to retry your request later.

Supported Data Formats

XMLJSON and Simple XML data formats are supported. You can specify the format that you require by setting the Accept request header.

The XML format includes namespace attributes on the root element of responses and requires them in requests.

Wisenet WebAPI requires XML tags to be in alphabetical order. When sending XML data specify HTTP request header “Content-Type: application/xml” When expecting to receive XML data specify HTTP request header “Accept: application/xml”

Sample request:

 curl -X GET \
   -u user:password \
   -H "Accept: application/vnd.mywisenet.api.v1+xml" \
   https://tst-api.wisenet.co/Students/

Sample response:

  <StudentSet xmlns="http://api.wisenet.co/v1/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <SetCount>1</SetCount>
    <Students>
      <Student>
        <AtsiStatus>
          <Code>@</Code>
          <Description>Not Stated (Question asked of the client but no answer provided)</Description>
        </AtsiStatus>
        <CountryOfBirth>
          <Code>3104</Code>
          <Description>Abruzzi | 3104</Description>
        </CountryOfBirth>
        <DateOfBirth>1970-01-01T00:00:00</DateOfBirth>
        <Disabilities>
          <Disability>
            <Description>Other</Description>
          </Disability>
        </Disabilities>
        <EmailAddress>fitzwilliam@darcy.com.au</EmailAddress>
        <EmploymentStatus/>
        <FirstName>Fitzwilliam</FirstName>
        <Gender>
          <Code>M</Code>
          <Description>Male</Description>
        </Gender>
        <HasPriorEducationalAchievement>Yes - a prior educational achievement has been successfully completed</HasPriorEducationalAchievement>
        <HighestSchoolLevelCompleted>
          <Code>12</Code>
          <Description>Completed Year 12</Description>
        </HighestSchoolLevelCompleted>
        <HighestSchoolLevelCompletedYear>2000</HighestSchoolLevelCompletedYear>
        <IsStillAtSchool>@</IsStillAtSchool>
        <LanguageSpokenAtHome>
          <Code>8998</Code>
          <Description>Aboriginal English, so described (8998)</Description>
        </LanguageSpokenAtHome>
        <LastName>Darcy</LastName>
        <LastUpdated>2012-01-25T10:52:46.65</LastUpdated>
        <Link>
          <Href>students/student/1</Href>
          <Rel>self</Rel>
          <Title>STD0000001: Fitzwilliam Darcy</Title>
        </Link>
        <Mobile>0411111111</Mobile>
        <MoodleAccessEnabled>false</MoodleAccessEnabled>
        <MyWiseNetAccountEnabled>false</MyWiseNetAccountEnabled>
        <PostalAddress>
          <AddressLine1>1 Darcy Street</AddressLine1>
          <AddressLine3>Parramatta</AddressLine3>
          <Country>
            <Code>1101</Code>
            <Description>Australia</Description>
          </Country>
          <PostCode>2150</PostCode>
          <State>
            <Code>01</Code>
            <Description>NSW</Description>
          </State>
        </PostalAddress>
        <PriorEducationalAchievements>
          <PriorEducationalAchievement>
            <Description>Certificate IV</Description>
          </PriorEducationalAchievement>
        </PriorEducationalAchievements>
        <RefInternal>STD0000001</RefInternal>
        <SpokenEnglishProficiency>
          <Code>2</Code>
          <Description>Well</Description>
        </SpokenEnglishProficiency>
        <StreetAddress>
          <AddressLine1>1 Darcy Street</AddressLine1>
          <AddressLine3>Parramatta</AddressLine3>
          <Country>
            <Code>1101</Code>
            <Description>Australia</Description>
          </Country>
          <PostCode>2150</PostCode>
          <State>
            <Code>01</Code>
            <Description>NSW</Description>
          </State>
        </StreetAddress>
        <StudyReason/>
        <SyncToSugar>false</SyncToSugar>
        <SyncToXero>false</SyncToXero>
        <TelephoneHome>0211111111</TelephoneHome>
        <TelephoneWork>0211111112</TelephoneWork>
        <Title>Mr</Title>
        <Username>fitzwilliam@darcy.com.au</Username>
      </Student>
    </Students>
  </StudentSet>

The JSON format uses JavaScript Object Notation.

  • When sending JSON data specify HTTP request header “Content-Type: application/json”
  • When expecting to receive JSON data specify HTTP request header “Accept: application/json”

Date&Time values are formatted in “\/Date(-39600000000+1100)\/” way.

Here 39600000000 is a number of ticks in milliseconds from 1 January 1970, e.g. C-Time and +1100 – timezone.

For more information please see http://stackoverflow.com/questions/206384/how-to-format-a-json-date

Also you can use the tool http://momentjs.com/docs/#/parsing/asp-net-json-date/

Sample request:

 curl -X GET \
   -u user:password \
   -H "Accept: application/vnd.mywisenet.api.v1+json" \
   https://tst-api.wisenet.co/Students/

Sample response:

    { 
        "SetCount" : 1,
        "Students" : [ { 
            "AtsiStatus" : { 
                "Code" : "@",
                "Description" : "Not Stated (Question asked of the client but no answer provided)"
            },
            "CountryOfBirth" : { 
                "Code" : "3104",
                "Description" : "Abruzzi | 3104"
            },
            "DateOfBirth" : "/Date(-39600000+1100)/",
            "Disabilities" : [ { 
                "Description" : "Other" 
            } ],
            "EmailAddress" : "fitzwilliam@darcy.com.au",
            "EmploymentStatus" : {  },
            "FirstName" : "Fitzwilliam",
            "Gender" : { 
                "Code" : "M",
                "Description" : "Male"
            },
            "HasPriorEducationalAchievement" : "Yes - a prior educational achievement has been successfully completed",
            "HighestSchoolLevelCompleted" : { 
                "Code" : "12",
                "Description" : "Completed Year 12"
            },
            "HighestSchoolLevelCompletedYear" : "2000",
            "IsStillAtSchool" : "@",
            "LanguageSpokenAtHome" : { 
                "Code" : "8998",
                "Description" : "Aboriginal Australian (8998)"
            },
            "LastName" : "Darcy",
            "LastUpdated" : "/Date(1328488553113+1100)/",
            "Link" : { 
                "Href" : "students/student/1",
                "Rel" : "self",
                "Title" : "STD0000001: Fitzwilliam Darcy"
            },
            "Mobile" : "0411111111",
            "MoodleAccessEnabled" : false, 
            "MyWiseNetAccountEnabled" : false,
            "PostalAddress" : { 
                "AddressLine1" : "1 Darcy Street",
                "AddressLine3" : "Parramatta",
                "Country" : { 
                    "Code" : "1101",
                    "Description" : "ACT"
                },
                "PostCode" : "2150",
                "State" : { 
                    "Code" : "01",
                    "Description" : "NSW"
                }
            },
            "PriorEducationalAchievements" : [ { 
                "Description" : "Certificate IV" 
            } ],
            "RefInternal" : "STD0000001",
            "SpokenEnglishProficiency" : { 
                "Code" : "2",
                "Description" : "Well"
            },
            "StreetAddress" : { 
                "AddressLine1" : "1 Darcy Street",
                "Country" : { 
                    "Code" : "1101",
                    "Description" : "ACT"
                },
                "PostCode" : "2150",
                "State" : { 
                    "Code" : "01",
                    "Description" : "NSW"
                }
            },
            "StudentId" : 1,
            "StudyReason" : {  },
            "SyncToSugar" : false,
            "SyncToXero" : false,
            "TelephoneHome" : "0211111111",
            "TelephoneWork" : "0211111112",
            "Title" : "Mr",
            "Username" : "fitzwilliam@darcy.com.au"
        } ]
    }

The Simple XML format is basically the same as the XML format, except that it does not include or require any namespaces on the root element. Also, elements can be provided in any order.

Sample request:

 curl -X GET \
   -u user:password \
   -H "Accept: text/xml" \
   https://tst-api.wisenet.co/Students/

Sample response:

  <StudentSet>
    <SetCount>1</SetCount>
    <Students>
      <Student>
        <AtsiStatus>
          <Code>@</Code>
          <Description>Not Stated (Question asked of the client but no answer provided)</Description>
        </AtsiStatus>
        <CountryOfBirth>
          <Code>3104</Code>
          <Description>Abruzzi | 3104</Description>
        </CountryOfBirth>
        <DateOfBirth>1970-01-01T00:00:00</DateOfBirth>
        <Disabilities>
          <Disability>
            <Description>Other</Description>
          </Disability>
        </Disabilities>
        <EmailAddress>fitzwilliam@darcy.com.au</EmailAddress>
        <EmploymentStatus />
        <FirstName>Fitzwilliam</FirstName>
        <Gender>
          <Code>M</Code>
          <Description>Male</Description>
        </Gender>
        <HasPriorEducationalAchievement>Yes - a prior educational achievement has been successfully completed</HasPriorEducationalAchievement>
        <HighestSchoolLevelCompleted>
          <Code>12</Code>
          <Description>Completed Year 12</Description>
        </HighestSchoolLevelCompleted>
        <HighestSchoolLevelCompletedYear>2000</HighestSchoolLevelCompletedYear>
        <IsStillAtSchool>@</IsStillAtSchool>
        <LanguageSpokenAtHome>
          <Code>8998</Code>
          <Description>Aboriginal English, so described (8998)</Description>
        </LanguageSpokenAtHome>
        <LastName>Darcy</LastName>
        <LastUpdated>2012-01-25T10:52:46.65</LastUpdated>
        <Link>
          <Href>students/student/1</Href>
          <Rel>self</Rel>
          <Title>STD0000001: Fitzwilliam Darcy</Title>
        </Link>
        <Mobile>0411111111</Mobile>
        <MoodleAccessEnabled>false</MoodleAccessEnabled>
        <MyWiseNetAccountEnabled>false</MyWiseNetAccountEnabled>
        <PostalAddress>
          <AddressLine1>1 Darcy Street</AddressLine1>
          <AddressLine3>Parramatta</AddressLine3>
          <Country>
            <Code>1101</Code>
            <Description>Australia</Description>
          </Country>
          <PostCode>2150</PostCode>
          <State>
            <Code>01</Code>
            <Description>NSW</Description>
          </State>
        </PostalAddress>
        <PriorEducationalAchievements>
          <PriorEducationalAchievement>
            <Description>Certificate IV</Description>
          </PriorEducationalAchievement>
        </PriorEducationalAchievements>
        <RefInternal>STD0000001</RefInternal>
        <SpokenEnglishProficiency>
          <Code>2</Code>
          <Description>Well</Description>
        </SpokenEnglishProficiency>
        <StreetAddress>
          <AddressLine1>1 Darcy Street</AddressLine1>
          <AddressLine3>Parramatta</AddressLine3>
          <Country>
            <Code>1101</Code>
            <Description>Australia</Description>
          </Country>
          <PostCode>2150</PostCode>
          <State>
            <Code>01</Code>
            <Description>NSW</Description>
          </State>
        </StreetAddress>
        <StudyReason />
        <SyncToSugar>false</SyncToSugar>
        <SyncToXero>false</SyncToXero>
        <TelephoneHome>0211111111</TelephoneHome>
        <TelephoneWork>0211111112</TelephoneWork>
        <Title>Mr</Title>
        <Username>fitzwilliam@darcy.com.au</Username>
      </Student>
    </Students>
  </StudentSet>

Was this Resource helpful?