Responses

A request that succeeds gets a 200 OK status line, a Content-Type: application/json header, and a body. The body is the representation of the resource. Now we decide what that representation looks like for each endpoint.

Returning one item

Here is the response to a request for one course:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "course_number": "EN.601.226",
  "title": "Data Structures",
  "credits": 4,
  "subject_area": "computer-science"
}

Four fields, one for each value the requirements say a course must return. The names are in lowercase with underscores. That is a convention. You can pick a different convention, but you have to be consistent.

The types matter as much as the names. credits is a number, 4, and not the string "4". A client that receives a number can add it up. A client that receives a string has to convert it first and has to guess what to do when the conversion fails. Pick the type that matches what the value is.

Here is one offering:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "offering_id": 8431,
  "term": "fall-2026",
  "course": {
    "course_number": "EN.601.226",
    "title": "Data Structures",
    "credits": 4
  },
  "professor": {
    "name": "Ali Madooei",
    "email": "madooei@jhu.edu"
  },
  "meeting_time": "Mon/Wed/Fri 10:00",
  "room": "Hackerman B17"
}

Everything the requirements list is here. The course fields and the professor fields are grouped into objects of their own, so a client can tell which fields describe the course and which describe the professor.

The course inside an offering does not include all its attributes. For example, it has no subject area. A client that wants it can request the course by its number.

Returning a list of items

Here is the response to a request for the courses in one subject area:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "course_number": "EN.601.220",
    "title": "Intermediate Programming",
    "credits": 4,
    "subject_area": "computer-science"
  },
  {
    "course_number": "EN.601.226",
    "title": "Data Structures",
    "credits": 4,
    "subject_area": "computer-science"
  }
]

The body is a list, and each member of it is a course with the same four fields as before. Here are the terms:

[
  {
    "code": "fall-2026",
    "name": "Fall 2026"
  },
  {
    "code": "spring-2027",
    "name": "Spring 2027"
  }
]

Each term has a code and a name. The name is for a person to read. The code is what the client sends back as the term query parameter. Subject areas have the same two fields.