- Created by Revathi Kotla, last modified on Sept 03, 2021
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 9 Next »
Introduction:
This wiki give the details about Viewer Service API(s) Spec design details.
Base Request Spec:
Authorization and x-authenticated-user-token are mandatory headers in every request
x-requested-by header is mandatory in all state update apis
{
"id": "api.view", // required. id of the api request
"ver": "1.0", // required. 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": { // required
....
....
}
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}}", // required
"contentId": "{{contentId}}" // required
"collectionId" : "{{collectionId}}" // optional.required
only when contextid is present
"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. required only when
contextId present in request
"contextId": "{{batchId}}", // optional
"progressDetails": {} // required. 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}}", //required
"contentId": "{{contentId}}" //required.
"collectionId" : "{{collectionId}}", // required.required 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}}", // required
"contentIds": ["{{contentId_1}}", "{{contentId_2}}"], //required
"collectionId" : "{{collectionId}}", //optional.required only when
contextId present in request
"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:
Sample1: Without context
{
"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: With context
{
"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}}", // required
"contentId": "{{contentId}}", // required
"collectionId" : "{{collectionId}}", // required
"contextId": "{{batchId}}", // required
"attemptId" : "{{attemptId}}", // required
"assessments": [{
{{assess_event}} // required 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}}": "Score Updated"
}
}
Content Assesment Read
POST - /v1/assessment/read
Request:
{
"request": {
"userId": "{{userId}}", //required
"contentId" : "{{contentId}}", //required
"collectionId" : "{{collectionId}}", //required
"contextId": "{{batchId}}" // required
}
}
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}}
}
]
}
}
Sample Response:
Sample1:
{
"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": "user_123",
"collectionId": "collection_123",
"contextId": "context_123",
"enrolledDate": 1624275377301,
"active": true,
"contentStatus": {
"content_123": 2,
"content_456": 1
},
"assessmentStatus": {
"content_123": {
"score": {{best_score}},
"max_score": {{max_score}}
}
},
"collection": {
"identifier": "collection_123",
"name": "Mathematics",
"logo": "http://logoimage",
"leafNodesCount": 4,
"description": "Dummy Collection"
},
"issuedCertificates": [{
"name": "Certificate-1",
"id": "cert_123",
"token": "sdfjkldjk23j2kj2k3jk2",
"lastIssuedOn": "1624275377301"
}],
"completedOn": "2021-09-10",
"progress": 70,
"status": 1
}
]
}
}
Viewer Summary - Specific enrolment
POST - /v1/summary/read
Request:
{
"request": {
"userId": "{{userId}}", // required
"collectionId" : "{{collectionId}}", // required
"contextId": "{{batchId}}" //required
}
}
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": {
"{{userid}}" : "Enrolment Deleted Succesfully"
}
}
DELETE - /v1/summary/delete/:userId - To Delete specific enrolments
Request:
{
"request": {
"userId": "{{userId}}", // required
"collectionId" : "{{collectionId}}", // required
"contextId": "{{batchId}}" // required
}
}
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": {
"{{userid}}" : "Enrolment Deleted Succesfully"
}
}
Viewer Summary Download - Default Format : 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.csv"
}
}
GET - /v1/summary/download/:userId?format=json
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
In the summary list api, if the context is program, how to show the program metadata
- No labels