Testy.me API Documentation

Welcome to the Testy.me API documentation. This API is designed for computer administrators to take advantage of our software to make integrating Testy.me seamless for your students and teachers.

Our web API follows the basic JSONAPI guidelines, and returns data in the JSON format. We do not currently have any support for any other formats like XML, but we may add this in the future on request.

Getting Started

Please read all of this Getting Started section - the most common issues people have when developing for our API is when they miss something from this section! TL;DR - read the "Public and Secret Keys" section to learn about our API authentication.

The entire API can be accessed through the HTTPS protocol using GET requests for passing variables. However, if a wrapper is available for your language, we recommend using this for ease of use and for security reasons.

Rate Limits

We currently do not enforce any rate limits, but the use of this API is under fair use. We'll contact you if we have any queries regarding your use of our API. As per our Terms of Use, we can change this at any time without warning, or enforce a limit for any reason without warning. We'll only do this in extreme circumstances though, and we'll always try to give you notice.

For transparency, we'd like to tell you that we do record the amount of requests you make, but we don't record what requests you make. We won't enforce any limits automatically (every limit is manually placed), and any limit is only temporary.

Public and Secret Keys

In order to connect to our API, you'll need to retrieve your organisations public and secret API access keys. Each key is a random string of 30 characters. When logged into an administrator account, you can find your API keys under Account -> API Keys.

To prevent any unauthorised person making API calls on your behalf, you need to ensure that you keep your secret key a secret! Someone with your public and secret key could easily make API calls on your behalf and access the information of your accounts. If you believe someone has your secret key, you can generate a new one from within the administrator dashboard under Account -> API Keys. If you generate a new key, your old one will instantly be deactivated, so you'll have to edit any code using your existing key to use the new one to continue using the API.

Never include your secret key in any viewable code! If the source code for your language can be seen (like with JavaScript), do not include your secret key as someone could easily see and use it. Only use your secret key in places where someone else wouldn't be able to get it, like on your server with PHP. If you do need to make an API call from JavaScript, you should proxy your request through a PHP script (or your equivalent). To do this, make a PHP file that'll do the operation you want to do (and therefore contains your secret key) and point your AJAX request towards that instead of doing it directly in your JS.

When making a manual request using HTTPS, you need to ensure you also send your public and secret key, like so:

https://testy.me/api/v1/<call>?publicKey=your_public_key&secretKey=your_secret_key

Wrappers

At the moment, we only currently have a wrapper for PHP. This wrapper requires PHP 5.4 or higher, and hasn't been tested on any version below that. The wrapper may work on other versions with modifications, but this isn't recommended.

Download "Testy.me API Wrapper V1.0 for PHP 5.4 and higher"

All of our official wrappers use object-orientated programming where possible, and so a basic understanding of OOP in your selected language is highly recommended.

Place the PHP wrapper file into whichever directory works best for you, then in your PHP code which you'd like to use the API, make sure you require it.

require 'location/to/my/testy-api.php';

To get started, you'll need to create an object of the API class to make your API calls. Because we're using OOP, you could technically connect on behalf of multiple institutions if you needed to. We've named our object "$testy", but you can call it whatever you'd like, as long as you keep the consistency. Throughout this documentation, we'll be using the object name "$testy", however.

$testy = new testymeapi("your_public_key", "your_secret_key");

Global Callbacks

As per the JSONAPI guidelines, all of our callbacks will give the same global values to help you troubleshoot errors.

jsonapi: {
	version: "1.0"
},
response: {
	status: "200",
	code: "success",
	title: "Successful API call!"
}

Status / Error Codes

We use the standard HTTP status codes. You can use these for debugging your requests to see what is going wrong, or to check if something has gone wrong on the fly. To check if something has gone wrong on the fly, you can check the status or the code. We strongly advice against checking the title attribute as this could change at any time and could be easy to get it wrong considering its length and punctuation.

Account Management

These procedures can be used for managing your user accounts.

Each procedure can be accessed using the HTTPS protocol using the direct URL, if you need to. For each procedure, we've explained both this approach and the wrapper approach.

login(username as string, password as string)

GET request

This function will log in a user and start their session if the username and password given is correct. This method of logging in will bypass some extra security features (such as location monitoring for suspicious logins).

https://testy.me/api/v1/login?username=<user>&password=<pass>

This method of logging in skips the institution query ("What school do you go to?") because your institution is linked with your public and secret key. Therefore, you could use this procedure to make your log in more streamlined, intuitive and recognisable for your students and teachers. If you want to handle authentication entirely, look at the loginDirect() procedure - use that if you want to use your existing log in system or a third-party one, like Login with Google.

To call this with our PHP wrapper, use the following function:

$result = $testy->login("myusername", "mypassword");

When successful, this procedure should give out a response similar to this:

response: {
	status: "200",
	code: "success",
	title: "Successful API call!"
},
identifier: "2",
institutionID: "1"

Make sure you don't forget to redirect your users on a successful login! You can redirect them to the home page (https://testy.me) and we'll handle the rest. We advise doing this over https://testy.me/dashboard because students and teachers redirect to different places.

loginDirect(identifier as string)

GET request

This call is designed to log directly into a user's account without a password, letting you handle authentication.

By using this function, you accept that you will be authenticating users yourself. When using this callback, we accept no responsibility for any users who manage to access accounts who are unauthorised to do so - you accept full responsibility. This function will authorise student and teacher accounts, but it will not authorise administrator accounts.

We only advise using this function if you want to integrate Testy.me into your existing log in system to improve the ease of use for your students and teachers. Using this function will bypass all of our security features, so you are relying on your own method to correctly and securely authenticate users. This call will not authorise administrator accounts - they have to log in the normal way for obvious security reasons.

https://testy.me/api/v1/loginDirect?identifier=<userID>

This API call requires you to give the user ID (identifier) of the user account that you want to log into with a GET request, as shown above.

To call this with our PHP wrapper, use the following function:

$result = $testy->loginDirect("32"); // Where 32 is the identifier...

On a successful call, you'll be logged into the user's session automatically. The function returns confirmation and returns the identifier and your institution ID, as shown below. Once you've received a successful response, you can redirect the user to https://testy.me, and they'll automatically be logged in.

response: {
	status: "200",
	code: "success",
	title: "Successful API call!"
},
identifier: "2",
institutionID: "1"

updatePassword(username as string, newPassword as string)

GET request

This procedure can be used to update the password of a student or teacher account. You'll need to provide the username of the account you want to change, and the new password. Using this function will not cause any emails to be sent regarding the password change, you can do this yourself if you want to.

https://testy.me/api/v1/updatePassword?username=<user>&newPassword=<pass>

To call this with our PHP wrapper, use the following function:

$result = $testy->updatePassword("myusername", "mynewpassword"); 

When successful, this API call will return the following information:

response: {
	status: "200",
	code: "success",
	title: "Successful API call!"
},
identifier: "2",
institutionID: "1"

For security reasons, we won't return the changed password for verification.

Analysis (Getters)

These procedures can be used for getting facts and figures regarding your students. This could be useful for any data analysis you might want to do. Please note that we have plenty of tools to help with this in the teacher and administrator dashboard, so consider looking at those to see if they are sufficient before creating your own.

getLastLogin(username as string)

GET request

This procedure will return the date in the UNIX timestamp format of when the user entered last actively logged into their account.

https://testy.me/api/v1/getLastLogin?username=<user>

To call this with our PHP wrapper, use the following function:

$result = $testy->getLastLogin("myusername"); // Returns a UNIX time stamp

When successful, this API call will return the following information:

response: {
	status: "200",
	code: "success",
	title: "Successful API call!"
},
identifier: "2",
lastLogin: "1489663879"