- Created by Revathi Kotla, last modified on Sept 02, 2021
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 3 Next »
Introduction:
This wiki give the details about Viewer Service API(s) Spec design details.
Base Post Request Spec:
{
"id": "api.view", // mandatory. id of the api request
"ver": "1.0", // mandatory. Current version of api
"ts": "2021-01-01T00:00:00+05:30", //mandatory. Timestamp of the request
"params": {
"msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341" // unique request message id, UUID
},
request: {
// request data
}
API Spec
Content View Start
POST - /v1/view/start
Request Spec:
{
"id": "api.view.start",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
},
"request": {
"userId": "{{userId}}",
"contentId": "{{contentId}}"
"collectionId" : "{{collectionId}}" // optional
"contextId": "{{batchId}}" // optional
}
}
Sample Requests:
Sample1: consume organic content
SampleRequest1
{
"id": "api.view.start",
"ver": "v1",
"ts": "2021-06-23 05:37:50:175+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
}
"request": {
"userId" : "user_123",
"contentId" : "content_123"
}
Sample2: consume content through collection
{
"id": "api.view.start",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
}
"request": {
"userId" : "user_123",
"contentId" : "content_123",
"collectionId" : "collection_123"
}
Sample3: consume content through context
{
"id": "api.view.start",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
}
"request": {
"userId" : "user_123",
"contentId" : "content_123",
"collectionId" : "collection_123",
"contextId" : "context_123"
}
Response:
200 Ok Response:
{
"id": "api.view.start",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"{{contentId}}": "Progress started"
}
}
4XX or 5XX Error Response:
{
"id": "api.view.start",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": ERR_Error_Code,
"status": "failed",
"errmsg": ERR_error_msg
},
"responseCode": "BAD_REQUEST"/"SERVER_ERROR",
"result": {
// error message
}
}
Sample Response:
Sample1: Valid Request
{
"id": "api.view.start",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"content_123": "Progress started"
}
}
Sample2: InValid Request
{
"id": "api.view.start",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": "CLIENT_ERROR",
"status": "failed",
"errmsg": ERR_error_msg
},
"responseCode": "BAD_REQUEST",
"result": {
"request.contentId": "Content Id cannot be empty"
}
}
Content View Update
POST - /v1/view/update
Request:
{
"id": "api.view.update",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
}
"request": {
"userId": "{{userId}}", // required
"contentId": "{{contentId}}", // required
"collectionId" : "{{collectionId}}", //optional. mandatory only when
contextId present in request
"contextId": "{{batchId}}", // optional
"progressDetails": {} // mandatory. Progress details specific
for each mimetype
}
}
Sample Requests:
Sample1: Without Context
{
"id": "api.view.update",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
}
"request": {
"userId" : "user_123",
"contentId" : "content_123",
"progressDetails" : {
"mimetype" : "appliation/pdf",
"progress" : 20,
"timespent" : 10
}
}
Sample1: With Context
{
"id": "api.view.update",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
}
"request": {
"userId" : "user_123",
"contentId" : "content_123",
"collectionId" : "collection_123",
"contextId" : "context_123",
"progressDetails" : {
"mimetype" : "application/pdf",
"progress" : 20,
"timespent" : 10
}
}
Response:
200 OK:
{
"id": "api.view.update",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"{{contentId}}": "Progress Updated"
}
}
4XX or 5XX Error:
{
"id": "api.view.update",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": ERR_Error_Code,
"status": "failed",
"errmsg": ERR_error_msg
},
"responseCode": "BAD_REQUEST"/"SERVER_ERROR",
"result": {
}
}
Content View End
POST - /v1/view/end
Request:
{
"id": "api.view.end",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
}
"request": {
"userId": "{{userId}}", //mandatory
"contentId": "{{contentId}}" //mandatory.
"collectionId" : "{{collectionId}}", // optional.mandatory only when
contextId present in request
"contextId": "{{batchId}}", // optional
}
}
Sample Request:
Sample1: Without Context
{
"id": "api.view.end",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
}
"request": {
"userId" : "user_123",
"contentId" : "content_123"
}
Sample2: With Context
{
"id": "api.view.end",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
}
"request": {
"userId" : "user_123",
"contentId" : "content_123",
"collectionId" : "collection_123",
"contextId" : "context_123"
}
Response:
{
"id": "api.view.end",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"{{contentId}}": "Progress ended"
}
}
Content View Read
POST - /v1/view/read
Request:
{
"id": "api.view.read",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
}
"request": {
"userId": "{{userId}}",
"contentIds": ["{{contentId_1}}", "{{contentId_2}}"],
"collectionId" : "{{collectionId}}", //optional
"contextId": "{{batchId}}" // optional
}
}
Response:
{
"id": "api.view.read",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"userId": "{{userId}}",
"collectionId": "{{collectionId}}", // optional
"contextId": "{{batchId}}", // optional
"contents": [{
"contentId": "{contentId}",
"status" : "{{content_status}}" // 0,1 or 2
"progressDetails": "{}"
}]
}
}
Sample Response:
Example1:
{
"id": "api.view.read",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"userId": "user_123",
"contents": [{
"contentId": "content_123",
"status" : "1",
"progressDetails": "{
"progress" :20,
"timespent" : 10
}"
}]
}
}
Example2:
{
"id": "api.view.read",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"userId": "user_123",
"collectionId" : "collection_!23",
"contextId" : "context_123",
"contents": [{
"contentId": "content_123",
"progressDetails": "{
"progress" :20,
"timespent" : 10
}"
status : "1"
}]
}
}
Content Submit Assess
POST - /v1/assessment/submit
Request:
{
"id": "api.assess.submit",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9"
}
"request": {
"userId": "{{userId}}", // mandatory
"contentId": "{{contentId}}", // mandatory
"collectionId" : "{{collectionId}}", // mandatory
"contextId": "{{batchId}}", // mandatory
"attemptId" : "{{attemptId}}", //mandatory
"assessments": [{
{{assess_event}} // mandatory for self-assess contents
}]
}
}
Response:
{
"id": "api.view.assess",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"{{contentId}}": "SUCCESS"
}
}
Content Assesment Read
POST - /v1/assessment/read
Request:
{
"request": {
"userId": "{{userId}}", //mandatory
"contentId" : "{{contentId}}", //mandatory
"collectionId" : "{{collectionId}}", //mandatory
"contextId": "{{batchId}}" // mandatory
}
}
Response:
{
"id": "api.assessment.read",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"userId": "{{userId}}",
"contentId" : "{{contentId}}"
"collectionId": "{{collectionId}}",
"contextId": "{{batchId}}",
"assessments": [{
"attemptId" : "{{attemptId}}",
"score": {{score}},
"max_score": {{max_score}}
},{
"attemptId" : "{{attemptId}}",
"score": {{score}},
"max_score": {{max_score}}
}
]
}
}
Viewer Summary - All enrolments
GET - /v1/summary/list/:userId
Response:
{
"id": "api.summary.list",
"ver": "v1",
"ts": "2021-06-23 05:59:54:984+0000",
"params": {
"resmsgid": null,
"msgid": "95e4942d-cbe8-477d-aebd-ad8e6de4bfc8",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"summary": [
{
"userId": "{{userId}}",
"collectionId": "{{collectionId}}",
"contextId": "{{batchId}}",
"enrolledDate": 1624275377301,
"active": true,
"contentStatus": {
"{{contentId}}": {{status}}
},
"assessmentStatus": {
"assessmentId": {
"score": {{best_score}},
"max_score": {{max_score}}
}
},
"collection": {
"identifier": "{{collectionId}}",
"name": "{{collectionName}}",
"logo": "{{logo Url}}",
"leafNodesCount": {{leafNodeCount}},
"description": "{{description}}"
},
"issuedCertificates": [{
"name": "{{certName}}",
"id": "certificateId",
"token": "{{certToken}}",
"lastIssuedOn": "{{lastIssuedOn}}"
}],
"completedOn": {{completion_date}},
"progress": {{progress}},
"status": {{status}}
}
]
}
}
Viewer Summary - Specific enrolment
POST - /v1/summary/read
Request:
{
"request": {
"userId": "{{userId}}", // mandatory
"collectionId" : "{{collectionId}}", // mandatory
"contextId": "{{batchId}}" //mandatory
}
}
Response:
{
"id": "api.summary.read",
"ver": "v1",
"ts": "2021-06-23 05:59:54:984+0000",
"params": {
"resmsgid": null,
"msgid": "95e4942d-cbe8-477d-aebd-ad8e6de4bfc8",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"userId": "{{userId}}",
"collectionId": "{{collectionId}}",
"contextId": "{{batchId}}",
"enrolledDate": 1624275377301,
"active": true,
"contentStatus": {
"{{contentId}}": {{status}}
},
"assessmentStatus": {
"assessmentId": {
"score": {{best_score}},
"max_score": {{max_score}}
}
},
"collection": {
"identifier": "{{collectionId}}",
"name": "{{collectionName}}",
"logo": "{{logo Url}}",
"leafNodesCount": {{leafNodeCount}},
"description": "{{description}}"
},
"issuedCertificates": [{
"name": "{{certName}}",
"id": "certificateId",
"token": "{{certToken}}",
"lastIssuedOn": "{{lastIssuedOn}}"
}],
"completedOn": {{completion_date}},
"progress": {{progress}},
"status": {{status}}
}
}
Viewer Summary Delete
DELETE - /v1/summary/delete/:userId?all - To Delete all enrolments
Response:
Response:
{
"id": "api.summary.delete",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {}
}
DELETE - /v1/summary/delete/:userId - To Delete specific enrolments
Request:
{
"request": {
"userId": "{{userId}}",
"collectionId" : "{{collectionId}}",
"contextId": "{{batchId}}"
}
}
Response:
Response:
{
"id": "api.summary.delete",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {}
}
Viewer Summary Download
GET - /v1/summary/download/:userId?format=csv
Response:
{
"id": "api.summary.download",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"url": "{{userId}}_viewer_summary.csv"
}
}
GET - /v1/summary/download/:userId
Response:
{
"id": "api.summary.download",
"ver": "v1",
"ts": "2021-06-23 05:37:40:575+0000",
"params": {
"resmsgid": null,
"msgid": "5e763bc2-b072-440d-916e-da787881b1b9",
"err": null,
"status": "success",
"errmsg": null
},
"responseCode": "OK",
"result": {
"url": "{{userId}}_viewer_summary.json"
}
}
Clarifications:
For assessment submit, do we need consider the assess events without context as well
- No labels