2

Should a resource be available through more than one URL endpoint?

For instance, I have exam resources which contain multiple question resources which in turn contain multiple answer resources. The endpoints to list questions and view a single question are as follows:

/api/exams/{exam_id}/questions
/api/exams/{exam_id}/questions/{question_id}

However, it also makes sense to be able to view a single question with an endpoint like:

/api/questions/{question_id}

Is it a bad idea to support additional endpoints for a single resource? If it is a bad idea, I think I'd rather have complex endpoints for collections and single resources because it seems inconsistent to simplify just one endpoint and have the following:

/api/exams/{exam_id}/questions
/api/questions/{question_id}

Going even further, there's also the complexity of multiple answer resource endpoints.

/api/exams/{exam_id}/questions/{question_id}/answers
/api/exams/{exam_id}/questions/{question_id}/answers/{answer_id}


/api/questions/{question_id}/answers
/api/questions/{question_id}/answers/{answer_id}


/api/answers/{answer_id}
mcon
  • 131
  • 2
    Does your requirements matrix, design document or software specifications state the need for an additional endpoint to support questions directly? If not, YAGNI. Build it when you can actually demonstrate a need for it. – Robert Harvey Aug 24 '17 at 16:35
  • @RobertHarvey It's not a requirement, but it's simple to add additional endpoints in the current implementation. I think the only need for it currently would be to simplify endpoints and make them slightly more intuitive. – mcon Aug 24 '17 at 16:44
  • How I would interpret the "/api/exams/{id}/questions/{id}" would be the questions for that specific exam. I would see "/api/question/{id}" as getting it out of a pool of all the questions. It may be the same result, but the interpretation is different. From the one you are limiting yourself to an exam, the other you are picking it from all the questions. – TanguyB Aug 25 '17 at 12:50
  • Take a look here. – Laiv Aug 27 '17 at 19:09

1 Answers1

1

Should a resource be available through more than one URL endpoint?

Only if you need it. Do you?

Is it a bad idea to support additional endpoints for a single resource?

It could be a bad idea only if you don't need it.

Take into account that REST API are contracts. Once in production, changing these contracts can be really challenging. Overall if we are enforced to support backward compatibility. Having to maintain YAGN-ish code reverts against our interest, so it's preferable to release only functional code.

How do we know if we need it?

Read carefuly the requirements because, this's rather an implicit need.

For example:

  1. Exams must be set only with available questions. Let's say that exams are set picking questions from a repository. If this is the case, the API should provide us with this repository. The repository -essentially- is the collection /api/questions.

  2. Certain roles are allowed to add new questions for further usage in different exams. Here, we are assuming several things: 1) questions don't necessarily belong an exam, 2) questions can be managed independently, 3) questions can belong to different exams. Any of these cases will lead you to provide the API with a repository of questions.

  3. Exam's questions are composed by the reference to its formulation and its valid answer, the committed answer, evaluator's side notes, the score, etc... Here, we are assuming that both URIs are not identifying the same resource. Questions within the scope/context of an exam are different than questions scoped from the repository.

It's not a requirement, but it's simple to add additional endpoints in the current implementation. I think the only need for it currently would be to simplify endpoints and make them slightly more intuitive.

Weight the pros & cons of that "slightly more intuitive". If the benefits of the so little improvement outweigh the costs of YAGNI (usually they don't), then go for it. Otherwise, just forget it.

Readings you might be interested

Laiv
  • 14,598
  • Thanks, this is really helpful! I'm going to read over everything a few more times just to make sure I understand fully, but I think points 1 and 2 are relevant for why I might include the endpoint. I have a handful of questions that don't have a parent exam and can be included on any exam. They exist in a sort of repository like you mention. Interacting with the repository questions through /api/questions seems appropriate for the system. – mcon Aug 28 '17 at 17:55