Proper way to link to related collection

1

I am trying to plan new API endpoints using jsonapi

but have a few questions.

  1. some articles I read say you can not use custom keys in the links object, and so I would not be able to use “links”: { “options”: “…” } for example as I am … so is that true? because other questions i’ve read on here seem to just accept it

  2. if I can’t, then how should I accomplish this… I want the to supply the client with the hyper media links so it knows where to go to find the related resource collections.

  3. this is my first try using jsonapi so any other constructive criticism is welcome.

GET /exam/123

{
  "data": {
    "type": "exam",
    "id": 123,
    "attributes": { ... },
    "relationships": {
      "creator" {
        "data": {"type": "user", "id": 20}
      },
      "last_updated_by": {
        "data": {"type": "user", "id": 20}
      }
    },
    "included": [
      { "type": "user", "id": 20, "attributes": { ... }  }
    ]
  },
  "links": {
    "questions": "/exam/123/questions"
    "first_question": "/exam/question/1101"
  }
}

GET /exam/123/questions?page[number]=3&page[size]=1

{
  "meta": {
    "totalPages": 13
  },
  "data": [{
    "type": "exam_question",
    "id": 1103,
    "attributes": {
      "text": "Which of the following are prime numbers",
      "display_order": 3,
      "type": "multiple_choice",
    },
    "links": {
      "question": "/exam/question/1103",
      "options": "/exam/question/1103/options"
    }
  }],
  "links": {
    "self": "/exam/123/questions?page[number]=3&page[size]=1",
    "first": "/exam/123/questions?page[number]=1&page[size]=1",
    "prev": "/exam/123/questions?page[number]=2&page[size]=1",
    "next": "/exam/123/questions?page[number]=4&page[size]=1",
    "last": "/exam/123/questions?page[number]=13&page[size]=1"
  }
}

GET /exam/question/1103

{
  "meta": {
    "totalQuestions": 13
  }
  "data": {
    "type": "exam_question",
    "id": 1103,
    "attributes": {
      "text": "Which of the following are prime numbers",
      "display_order": 3,
      "type": "multiple_choice"
    }
  },
  "links": {
    "first": "/exam/question/1101",
    "prev": "/exam/question/1102",
    "self": "/exam/question/1103",
    "next": "/exam/question/1104",
    "last": "/exam/question/1113"
    "options": "/exam/question/1103/options"
  }
}

GET /exam/question/1103?include=options

{
  "meta": {
    "totalQuestions": 13
  }
  "data": {
    "type": "exam_question",
    "id": 1103,
    "attributes": {
      "text": "Which of the following are prime numbers",
      "display_order": 3,
      "type": "multiple_choice"
    },
    "relationships": {
      "options": {
        "data": [
          {"id": 3011, "type": "question_option"},
          {"id": 3012, "type": "question_option"},
          {"id": 3013, "type": "question_option"},
          {"id": 3014, "type": "question_option"},
        ]
      }
    }
  },
  "included": [{
    "type": "question_option",
    "id": 3011,
    "attributes": {
      "display_order": 1,
      "text": "13"
    }
  }, {
    "type": "question_option",
    "id": 3012,
    "attributes": {
      "display_order": 2,
      "text": "27"
    }
  }, {
    "type": "question_option",
    "id": 3013,
    "attributes": {
      "display_order": 3,
      "text": "33"
    }
  }, {
    "type": "question_option",
    "id": 3014,
    "attributes": {
      "display_order": 4,
      "text": "all of the above"
    }
  }],
  "links": {
    "first": "/exam/question/1101",
    "prev": "/exam/question/1102",
    "self": "/exam/question/1103",
    "next": "/exam/question/1104",
    "last": "/exam/question/1113",
    "options": "/exam/question/123/options"
  }
}

GET /exam/question/1103/options

{
  "data": [{
    "type": "question_option",
    "id": 3011,
    "attributes": {
      "display_order": 1,
      "text": "13"
    }
  }, {
    "type": "question_option",
    "id": 3012,
    "attributes": {
      "display_order": 2,
      "text": "27"
    }
  }, {
    "type": "question_option",
    "id": 3013,
    "attributes": {
      "display_order": 3,
      "text": "33"
    }
  }, {
    "type": "question_option",
    "id": 3014,
    "attributes": {
      "display_order": 4,
      "text": "all of the above"
    }
  }],
  "links": {
    "question": "/exam/question/1103"
  }
}