Guide 1.6: Developer Guide

Understanding SdashAPI Responses

When you make a successful request to SdashAPI, our servers respond with a structured data format called JSON. This guide breaks down the anatomy of a standard V1 API response so you know exactly how to extract the questions and answers.

The Anatomy of a Response

1.6.1

Every response you receive will contain a status code and a data payload. The status indicates if the request was successful (200) or if an error occurred. The data object contains the actual examination content.

{
  "status": 200,
  "data": {
    "id": 10432,
    "question": "Evaluate 2x + 3y if x = 2 and y = 4",
    "option": {
      "a": "16",
      "b": "14",
      "c": "12",
      "d": "10"
    },
    "answer": "a",
    "solution": "Substitute the values: 2(2) + 3(4) = 4 + 12 = 16. The correct answer is A.",
    "examtype": "JAMB",
    "examyear": "2022"
  }
}

Key Data Fields Explained

1.6.2

The data object provides everything you need to render a question in your application:

question: The actual text of the examination question. Sometimes this includes HTML tags (like <sup> or <br>) for proper formatting of math formulas or new lines.
option: An object containing choices (a, b, c, d, and sometimes e). You should map over this object to generate the radio buttons in your UI.
answer: The correct option letter (e.g., "a"). Use this to evaluate if the user's selected option is correct.
solution: A step-by-step written explanation of how to arrive at the correct answer. This is incredibly valuable for educational platforms.
examtype & examyear: Metadata indicating the origin of the past question.

Missing Options (Null Values)

1.6.3

It is important to note that not all questions have 5 options. For example, some WAEC questions only provide options A through D. In these scenarios, the option object will still contain an e key, but its value will be null.

When building your frontend user interface, you must always verify that an option is not null before rendering a radio button for it. This prevents empty checkboxes or blank options from appearing in your application.

Error Responses

1.6.4

If something goes wrong (such as querying a subject that does not exist or forgetting your API key), the API will return a 400 or 500-level status code, and the JSON payload will look different.

{
  "status": 404,
  "message": "Subject not found or no questions available for this exam type."
}

Instead of a data object, you will receive a message string explaining exactly what went wrong. Your application should always check the status property first before attempting to read the data payload.

How do I use this data?

Next, we will learn how to parse and manipulate this JSON data in your code.