OLD 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 Root
• Course Offers
  • Course Enrolments
  • Course Enrolments’ Documents
  • Unit Offers in Course Offer
• Students
  • Student Positions
  • Student’s Course Enrolments
  • Student’s Next of Kin
  • Student’s Positions
  • Student’s Unit Enrolments
• Unit Offers
  • Unit Enrolments
• References Endpoint
• Workplaces Endpoint

API Entity Relationships

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 v6
  • V6 has slight changes to some options in Country and Language

Client Tools

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

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