by Jeny Amatya1

10 September 2025

Last updated 10 September 2025

Getting started

Quick Start: Using the API portal - Draft 🚀

Welcome to the API portal! Whether you are just starting out or already an experienced developer, this guide will walk you through everything you need to start using our APIs.

1. Getting started (for new API developers)

What is an API?

Think of an API as a school receptionist:

You (the caller) ask for something → “What’s today’s timetable for Year 9 Science?”
The receptionist (API) checks the system.
You get a neat, structured reply (in JSON, like a printed timetable sheet).

JSON (JavaScript Object Notation):
Like a report card – it uses labels and values.

{
  "subject": "Science",
  "teacher": "Ms. Smith",
  "room": "B204"
}

2. Getting ready (Before you call an API)

Step 2: Create an application key 🆔

~~This is your school ID card. Without it, the system won’t recognise you.~~ [add screenshot]

Go to APIs → My applications.
Click on ‘Create an API key’ button.
Name your app (e.g., “QTeacher Integration App”).
Copy the API key by using the copy icon.

Step 3: Know your permissions

~~Some APIs are public, others require extra access. Think of it like different staffroom keys – you may only access certain rooms (systems).~~ All APIs are public at the moment.

3. Exploring APIs in the sandbox (for beginners) 🧪

The Sandbox is like a practice exam – a safe space to try before you go live. [add screenshot]

Go to the API catalogue
Select an API product within the catalogue (e.g., QTeachers catalogue - >Staff)
Select the API endpoint.
Enter parameters (like centreCode = 12345)

Click on Execute button and see the JSON response

[
  {
"staffCentreId": "90087",
"staffId": "84748",
"title": "Mr.",
"familyName": "Reynolds",
"givenNames": "Layla",
"timetableCode": "HOMEMI",
"staffType": {
  "code": "D",
  "description": "Departmental"
},
"staffStatus": {
  "code": "A",
  "description": "Active"
},
"gender": {
  "code": "F",
  "description": "Female"
}
  },...

4. Using Postman & other tools (for intermediate developers) 🧑‍🔬

Think of Postman as your school lab – you can experiment with different setups.

Download and install Postman.
Import endpoints
1. From the API catalogue, download the OpenAPI specs
2. In Postman, click Import -> upload the file
3. You can see all the endpoints
Add application key
1. In Postman, open the Headers tab.
2. Add the entry for X-API-KEY.
3. Paste the application key.
Run a request
1. Pick an endpoint (e.g. https://dp-mockaco.azurewebsites.net/QT_staff/school-api/schools/111/staff )
2. Enter parameters (eg. centreCode=111)
3. Click Send and you will get the results. [add screenshot]
```
Add results here
```
  Pro Tip: Save collections in Postman so you don’t have to re-enter every time.💡 [add screenshot]

5. Integrate our APIs in your app (for hands-on coders) 💻

Once you’re comfortable testing, you can integrate the APIs into your own applications.

Authentication

Every request must include your Application Key:

In the headers (e.g., X-API-KEY: <key>),

Example: cURL

curl -X GET "https://dp-mockaco.azurewebsites.net/QT_staff/school-api/schools/111/staff?centreCode =1245" \
      -H "X-API-KEY: YOUR_APP_KEY"

Example: node.js

const axios = require("axios");

axios.get("https://dp-mockaco.azurewebsites.net/QT_staff/school-api/schools/111/staff?centreCode =1245", {
  headers: { "X-API-KEY": "YOUR_APP_KEY" }
})
.then(res => console.log(res.data))
.catch(err => console.error(err));

Example: Python

import requests

url = "https://dp-mockaco.azurewebsites.net/QT_staff/school-api/schools/111/staff?centreCode =1245"
headers = {
    "X-API-KEY": "YOUR_APP_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

Example: C#

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-KEY", "YOUR_APP_KEY");

var response = await client.GetStringAsync("https://dp-mockaco.azurewebsites.net/QT_staff/school-api/schools/111/staff?centreCode =1245");
Console.WriteLine(response);

6.Handling Errors (Common Pitfalls) 🛠

401 Unauthorized → Did you forget your application key?
403 Forbidden → You don’t have permission.
404 Not Found → The record doesn’t exist (wrong student ID).