Rework the HTTP API to be more resource oriented
Currently the APIs available through HTTP follow a more "function" based approach, with question services having one URL to handle all their instances and another one for all their answers. However details about which instance to handle are provided with the sent body (especially for the POST messages).
For example to list all instances with a specific category the following message is sent to POST https://...amazonaws.com/Question-SingleChoiceRadioButton
:
{
"action": "l"
"categories": "business-fit"
}
Another example to update an instance the following message is sent to the same endpoint:
{
"action": "u",
"instanceId": "scrb_8f2bc99a-63a8-447a-8da8-dc0fd6d76eb8",
"label": "updated basic testing instance",
"details": {
"question": "How do you feel???",
"possibleAnswers": ["good", "fine", "ok", "not ok", "bad"]
}
}
As far as I can tell we have currently resources based on three parts:
- typeId - what type of question, for example
Question-SingleChoiceRadioButton
. - instanceId - the identifier for a question instance which is of a specific type.
- sessionId - the session for which there is an answer for a specific question instance.
typeId --> instanceId --> sessionId
A more resource oriented interface should not hide "instances" of the concepts in the message. Instead they should be part of the URL, preferably as part of the path. The structure for the URLs could look like the following for the different functions:
- QI Create instance:
POST https://...amazonaws.com/[typeId]
and/orPUT https://...amazonaws.com/[typeId]/[instanceId]
(if it should have a specific instanceId) - QI Read instance:
GET https://...amazonaws.com/[typeId]/[instanceId]
- QI Update instance:
PUT https://...amazonaws.com/[typeId]/[instanceId]
- QI Delete instance:
DELETE https://...amazonaws.com/[typeId]/[instanceId]
- QI Present instance:
GET https://...amazonaws.com/[typeId]/[instanceId]/presentation
- QI List instances:
GET https://...amazonaws.com/[typeId]
- QI Test details for instance:
POST https://...amazonaws.com/[typeId]/test
- QA Create answer:
PUT https://...amazonaws.com/[typeId]/[instanceId]/answers/[sessionId]
- QA Read answer/s:
GET https://...amazonaws.com/[typeId]/[instanceId]/answers/[sessionId]
and/orPOST https://...amazonaws.com/[typeId]/[instanceId]/answers
to handle multiple sessions and/orGET https://...amazonaws.com/[typeId]/[instanceId]/answers
to read for all sessions - QA Update answer:
PUT https://...amazonaws.com/[typeId]/[instanceId]/answers/[sessionId]
- QA Delete answer:
DELETE https://...amazonaws.com/[typeId]/[instanceId]/answers/[sessionId]
- QA Present answer:
GET https://...amazonaws.com/[typeId]/[instanceId]/answers/[sessionId]/presentation
- QA List sessions having answer:
GET https://...amazonaws.com/[typeId]/[instanceId]/answers/
- QA Test answer:
POST https://...amazonaws.com/[typeId]/[instanceId]/answers/test
QI: Question Instance
QA: Qestion Answer
The "action" style message could still be supported on the POST URLs that are for a specific QI or QA