WiseNET API: Developer Resources

From Wisenet Resource Centre
Jump to: navigation, search

Contents

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.

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

API entity relationships.PNG

Dropdown Lists

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 v4.

ClientIn Wise.NET a client is a student, trainee or apprentice Tools

cURL utility

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

Recommended API test client

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:

Please see the Postman page with sample call to the Student endpoint below


PostmanApiCall.jpg

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/ ClientIn Wise.NET a client is a student, trainee or apprentice RefInternalUnique student identifier automatically produced by Wise.NET. Compare RefExternal 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 access.

Also you can check [1] "ClientIn Wise.NET a client is a student, trainee or apprentice 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 and if you have exceeded your quota you will receive error code 403 (Forbidden). There are also additional fair use limits to protect WiseNET from abuse or excessive load.

Please see below "Error handling - HTTP codes".

Limit is: 1000 calls per 24 hour sliding window per organisation.

Sending and retrieving resources

Retrieving resources

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

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.

Sending resources

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

Validation and Error handling

Validation

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

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.

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:

HTTP Code Mnemonic GET GET{id} POST PUT{id}
200 OK + + + +
204 NoContent +
400 BadRequest + + +
401 Unauthorized * * * *
403 Forbidden + + + +
404 NotFound + +
405 MethodNotAllowed
500 InternalServerError + + + +
501 NotImplemented

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

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

XML

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>
        <RefInternalUnique student identifier automatically produced by Wise.NET. Compare RefExternal>STD0000001</RefInternalUnique student identifier automatically produced by Wise.NET. Compare RefExternal>
        <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>

JSON

The JSON format uses JavaScript Object Notation.

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" 
            } ],
            "RefInternalUnique student identifier automatically produced by Wise.NET. Compare RefExternal" : "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"
        } ]
    }

Simple XML

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>
        <RefInternalUnique student identifier automatically produced by Wise.NET. Compare RefExternal>STD0000001</RefInternalUnique student identifier automatically produced by Wise.NET. Compare RefExternal>
        <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>
Personal tools
Namespaces
Variants
Actions
Navigation
Translate
Wisenet Getting Started
Learning Relationship Management
Learner App
Trainer Portal
Wise.NET Portal
CRM
eLearning
Surveys
Finance
Application Integration
Compliance: Australia
Compliance: New Zealand
Developer Resources
Toolbox