In this article, we will provide an outline of the URL structure, as well as the request and response formats used by the Class API.
URL structure
All endpoints in the Class API utilise a common URL structure as follows:
https://api.class.com.au/api/{version}/{scope}/{area}/{action}
|
URL Component
|
Description
|
|---|---|
| version | The API version, currently the only valid value for this component is 1.0. |
| scope | The scope of the requested resource:
|
| area | Endpoints are grouped into areas based on the resources on which they operate. For instance, fund-data contains actions related to funds and member-data contains actions related to members |
| action | Identifies the specific resource and the requested action. e.g. GET member-detail/35572c36-9d63-4be5-a86f-072040a2781e would retrieve the details of the member with id 35572c36-9d63-4be5-a86f-072040a2781e |
Examples of valid URLs:
https://api.class.com.au/api/1.0/b/Business/fund-data/fund-list
https://api.class.com.au/api/1.0/f/Business/Fund/member-data/member-detail/35572c36-9d63-4be5-a86f-072040a2781e
Request headers
The Class API makes use of a variety of HTTP headers to determine request behaviour, as detailed in the following table.
|
Header
|
Description
|
|---|---|
| Accept | Specifies the media type and action version for the response.
Currently supported media types are application/json and application/xml. The action version should be specified in the following format: vnd.superip.action.v{version}. The acceptable values for {version} depend on the specific action being requested, but in the initial version of the API should always be 1. If the Accept header is not supplied, the media type for the response defaults to application/xml and the action version defaults to the oldest available version for the requested action. Examples of valid Accept header values:
|
| Content-Type | Specifies the media type for the request body.
Currently supported media types are application/json and application/xml. If the Content-Type header is not supplied, the server will interpret the request body as xml. Examples of valid Content-Type header values:
|
| Authorization |
When making requests to the Class API, the access token must be sent in the HTTP authorization header. The header must be in the Bearer token format: The authorization header is case-sensitive, including the word Bearer. Example of Valid Authorization header value:
Where Orh1Vz8T... is the access token issued |
Response format
Responses from the Class API use a common structure for reporting errors and returning data:
{
"Errors": [
{
"Code" : "ErrorCode",
"Message" : "A detailed, human-readable message explaining the error"
},
...
],
"Data" : { ... }
}
For unsuccessful requests:
The Errors element will contain a list of error codes and readable messages, informing you of the erroes encountered. The Data element will be empty.
For successful requests:
The Errors element will be empty.
The Data element will contain the requested data (if any). The format of the Data element is endpoint dependent and described in the documentation for each endpoint that returns data.
Response code overview
The table below provides an overview of the various HTTP status codes that can be returned by the Class API.
|
Status Code
|
Name
|
Description
|
|---|---|---|
| 200 | OK | Request completed successfully. |
| 400 | Bad Request | An error occurred processing the request. An appropriate error code and description are included in the response body, see Requests and Responses for more details. |
| 401 | Unauthorized |
|
| 404 | Not Found |
The requested resource could not be found.
|
| 406 | Not Acceptable | The Accepts header in the request did not contain any supported media types. See the Requests and Responses section for details on supported media types. |
| 415 | Unsupported Media Type | The request specified an unsupported Content-Type header. See the Requests and Responses section for details on supported content types. |
| 500 | Internal Server Error | An unhandled error occurred while processing the request. Please report this error to Class. |
| 501 | Not Implemented | The request specified an API version or Action Version that is not supported. See the Requests and Responses section for details of API versioning. |
| 503 | Unavailable | Class servers are down for maintenance or otherwise not available to service requests. |