Format: 1A

WebAssess API documentation

NOTE: this is a draft, on-going attempt to document the API. If things are missing or don’t work as described here, please get in touch.

Overview

The API uses the REST syntax but the semantics, due to the requirements, are a bit different. The backend maintains state information on behalf of the client. This is a requirement: it’s needed in order to prevent cheating and to enforce the rules and logic of the tests. (E.g. to prevent movig backwards withing the test if that has been setup that way. Also, in general, the client should only be able to navigate between the questions according to the rules defined by the server.)

Endpoints

All endpoint urls below are relative to the API root url path, which is: /api/v1/ if they don’t start with a /. The ones that do are absolute ones. We have a development and a production deployment at https://staging.webassess.com and https://app.myinnergenius.com/ respectively.

Authentication

All requests should be authenticated with a valid token passed in the Authorization header, using the Token scheme. E.g.: Authorization: Token <token_from_the_api> . NOTE that the auth endpoints have an absolute path which means that they should be appended to the server URL directly (ignoring the API root url path).

Logging in [POST] /rest-auth/login/

Information about the logged-in user [GET] /rest-auth/user/

Start an assessment (using a specific specified test battery) [POST] batteries/{id}/assessments/

Create a new assessment based on the battery specified by the id. A user can only have one active assessment per test battery. If the user already

Fetch test elements [GET] assessments/{assessment_id}/next/

A TestBattery (and thus an Assesssment) consists of TestElements. At the moment there are two type of elements: pages and groups. A group is a group of related questions. This endpoint returns the next test elements to be displayed. Repeat calls may or may not return the same result. E.g. if an element is timed (e.g. in case of a timed group or because the including test has a time limit) and the time is up between two successive calls, then the response contents will be different even if the client didn’t make any calls that could have changed the state of the assessment (e.g. by submitting a response).

Get results (for a specific assessment) [GET] assessments/{assessment_id}/results/

Users can only access their own results.

List Candidates [‘GET’] /candidates/

Get single Candidate [‘GET’] /candidates/{id}/

TODO: simply return a different format here or use a format specifier (e.g. format=full)?

Update candidate / set favorite status [‘PUT’, ‘PATCH’] /candidates/{id}/

The resource supports partial updates.

Update position (hiring decision) [‘POST’] /candidates/{id}/position/

Create (update) hiring decision for candidate. Technically hiring decisions are immutable, we keep a history, so you can only create a new one and not change existing ones. The valid one is always the last decision. When creating a hiring decision provide only one of jobId or customName. To indicate a no hire provide none (e.g. by posting an empty object).

Group Assessments

This section only describes the endpoints in use by the client admin in this group, but there are some others in use by the test-taking app. Those are not documented yet.

List Assessments [‘GET’] /assessments/

Returns the list of assessments the current user has access to. (I.e. ones that belong to candidates that they have permission to view.)

Group Assessment reporting (results)

List assessments with results if available [‘GET’] /reports/assessments/

Get the results for a specific assessment [‘GET’] reports/assessments/{id}/

See response above.

Group Jobs

Get List of Jobs [‘GET’] /jobs/

Get single Job [‘GET’] /jobs/{id}/

Group TestBatteries

List TestBatteries [‘GET’] /batteries/

Get a single TestBattery [‘GET’]

Group Invitations

Create Invitation [‘POST’] /invitations/

Create an invitation and optionally send an invite email.

List invitations [‘GET’]

Create (send) Invitaions in bulk [‘POST’] /batteries/{id}/invitations/

Send out email invitations for the specified battery.

You can provide any or both of emails or file.

Accepted MIME types and the respective file formats: + application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - XLSX + application/vnd.ms-excel - XLS + text/csv - CSV

Group data export / spreadsheet download

These endpoints allow donwloading specific datasets belonging to some of the above endpoint in a spreadsheet format (either CSV or XLSX). The format is specified via the Accept header, the default being CSV. These endpoints are separate from the JSON endpoints for two reasons: * the logical structure is different as JSON is hierarchical and the spreadsheets are flat * some of the logic behind the spreadsheet endpoints is also used for data export in the admin. While this is an implementation detail, doing it this way prevents code duplication that would arise if we wanted to flatten the original output format of the above endpoints

Export assessments (‘report’ functionality) [‘GET’] ‘/export/assessments/’

The filtering and ordering options are the same as with the /candidates/ endpoint. The page_size parameter is ignored. The file name to use for saving the file is returned in the Content-Disposition header. The returned spreadsheet format can be selected with the Accept request header. As of now two formats are supported: CSV (text/csv) and XSLX (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).

Group Locations

A Location belongs to a Company and Candidates are always assigned to one. Admin users are also organized by locations and, depending on their permission level, they may be able to see the candidates assigned to one or more locations (besides their own, invited candidates).

List locations [‘GET’] /location/

Only admin users with the right set of privileges can do this. Missing priviliges will lead to a 403 error (or an empty result list).

Create location [‘POST’] /locations/

Get individual location [’GET] /locations/{id}/

See response format above

Update location [‘PUT’, ‘PATCH’] /locations/{id}/

Data Structures

Group (object)

Question (object)

ComparisonQuestion

This type has the following extra fields:

Page

Badge (object)

Screenshots

Sample screenshots from the current web app to help visualizing how data from the API should (can) be rendered and what each of them mean.

Potential problems with non-web clients

As you can see from the API, the groups and questions carry their own layout as a VueJS template. This template will control both the layout and some of the content (it may have additional text not present in the data fields). An ideal mobile client would be able to render these templates. To provide a native L&F, we’d have to serve vue-native (or react native) templates, though. (Vue-native can be compiled to react native.) To do so, we’d also have to use these for the web app (e.g. through vue-native -> react-native -> react-native-web) or we’d have to have and serve different templates for different clients (which do make a lot of sense).

However, these are out of scope for now, so the mobile client will have to provide its own rendering code. The problem you’ll face here is that due to the above design decision (each group having their own template), the same question type (see Question.resourcetype) can have a different look/layout.

E.g. all the above screenshots contain multiple choice questions, but they do come in different layouts. The API doesn’t provide a way to differentiate between the preferred layouts. What you can do for now is trying to guess based on the other parameters (e.g. group has description or not, number of choinces and maybe the test id).