Discussions - API Design

1 Request & Response Envelopes
2 NodeBB APIs
3 Sunbird APIs
- 3.1 Create User API
- 3.2 Create Forum API
- 3.3 Update Forum API
- 3.4 Fetch Forum API
- 3.5 Read Forum API
4 API Security
- 4.1 API Token
- 4.2 User Auth Token

Request & Response Envelopes

All API should follow the standard request and response structures:

Request Structure:

{
  "params": {
    "msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341" -- optional, random uuid
  },
  "request": {
    <RequestData of the API>
  }
}

Response Structure:

{
  "id": "API Id, e.g. api.forum.create",
  "ver": "API version, e.g. 1.0",
  "ets": "response timestamp in epoch format",
  "params": {
    "resmsgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341" -- random uuid,
    "msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341" -- the msgid sent in request
    "status": "successful or failed",
    "err": "error code if any",
    "errmsg": "error message if there is any error",
  },
  "responseCode": "OK, CLIENT_ERROR, RESOURCE_NOT_FOUND, SERVER_ERROR",
  "result": {
    <ResponseData of the API>
  }
}

NodeBB APIs

NodeBB provides the following APIs:

Read APIs: https://docs.nodebb.org/api/
Write APIs via plugin: nodebb-plugin-write-api/routes/v2/readme.md at master · NodeBB/nodebb-plugin-write-api

In addition to the above APIs, we need a few additional APIs to use NodeBB discussions in different Sunbird use cases.

Sunbird APIs

Sunbird Discussion APIs will use the following terminology:

Forum

A forum contains one or more discussion threads with one or more users participating in the discussions. Internally, forum is also a NodeBB category but there are some differences between a Sunbird forum and a NodeBB category:

Every forum is linked to a Sunbird context (e.g.: a Course batch).
A forum can have one or more NodeBB categories. E.g.: A course may have two categories - Announcements and General Discussions.
A forum can have a list of groups (with a set of permissions) associated with it & its sub-categories.

Hierarchy

Forum are organised into a hierarchy for easy discovery, navigation and access. For example, all forums belonging to an organisation can grouped under a parent forum. Example hierarchy:

CBSE
- Course
  - Classroom Management
    - Announcements
    - General Discussions
- Textbook
  - Science Textbook for Class X
  - Maths Textbook for Class IX
- Contribution Projects
  - KVS 6-8 Hindi & Science Textbooks

Permissions

Permissions are the list of privileges that user or group has in a forum. Instead of using NodeBB privileges, Sunbird APIs will support the following permissions:

read - nodebb privileges: 'topics:read', 'read', 'find'
vote - nodebb privileges: 'posts:upvote', 'posts:downvote'
post - nodebb privileges: 'topics:reply', 'posts:edit', 'posts:delete'
topic - nodebb privileges: 'topics:create', 'topics:tag'
moderate - nodebb privileges: 'topics:delete', 'posts:view_deleted', 'purge', 'moderate', 'posts:history'
- In addition to the above nodebb privileges, a user with “moderate” permission should be able to edit the current forum (using Update Forum API).

The permissions read, vote, post, topic and moderate are hierarchical. I.e., if a higher permission (e.g. topic) is given, all the below permissions (e.g. read, vote, and post) are automatically granted.

Create User API

Request Path: “/api/user/v1/create”

Method: “POST”

Request Structure

{
  "params": {
    "msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341" -- random uuid
  },
  "request": {
    “identifier”: “sunbird user id”,
    “username”: “sunbird user name”
  }
}

Response Structure

{
  "id": "api.discussions.user.create",
  "ver": "1.0",
  "ets": "1600883199000",
  "params": {
    "resmsgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341"
    "msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341",
    "status": "successful",
  },
  "responseCode": "OK",
  "result": {
    “identifier”: “sunbird oidc user id”
  }
}

Create User API will create a nodebb user for the given sunbird user id and username.

This API will be exposed by nodebb-plugin-sunbird-oidc plugin.
This API will throw an error if a user already exists with the given sunbird user id.
This API will create an email using the username and the configured email domain.

Create Forum API

Request Path: “/api/forum/v1/create”

Method:“POST”

Request Structure

{
  "params": {
    "msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341" -- random uuid
  },
  "request": {
    "name": "name of the forum",
    “context”: {
	  “type”: “batch / organisation / sb-group / content-collaboration / etc”,
	  “identifier”: “batch id or org id or sb-group id or content id, e.g: 012232323223232”
    },
    “parent”: "parent forum id under which the forum has to be created. optional, if not provided, this forum is created under the root",
    “groups” : [ // list of groups to be created and associated with the forum. group id will be auto-generated using a combination of the forum id and a random string/number
	  { “permissions”: [“read”, “vote”], "applyToChildren": "true/false" }, // permissions to be given for each associated group
      { “permissions”: [“read”, “vote”, “post”, “topic”, “moderate”], "applyToChildren": "true/false" }
    ],
    “privileges”: [ // set of permissions to be given for existing users or groups can also be provided
		{
			“permissions”: [“read”, “vote”, “post”, “topic”, “moderate”],
			“users”: [“list of sunbird user oidc ids”],
			“groups”: [“list of nodebb group ids”],
			"applyToChildren": "true/false, if these users/groups should be given same set of privileges in all the sub-forums"
		},
		{
			“permissions”: [“read”, “vote”, “post”, “topic”, “moderate”],
			“users”: [“list of sunbird user oidc ids”],
			“groups”: [“list of nodebb group ids”],
			"applyToChildren": "true/false"
		}
    ],
    "children": [ // list of sub-forums to be created
      {
        "name": "Name of the sub-forum", 
        "groups": [], // permissions for the sub-forum can be configured by associating groups or 
        "privileges": [] // giving privileges to existing users or groups
      }
    ]
  }
}

Response Structure

{
  "id": "api.discussions.forum.create",
  "ver": "1.0",
  "ets": "1600883199000",
  "params": {
    "resmsgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341"
    "msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341",
    "status": "successful",
  },
  "responseCode": "OK",
  "result": {
    “identifier”: “newly created forum id”
  }
}

Update Forum API

Request Path: “/api/forum/v1/update/<forum_id>”

Method:“PATCH”

Request Structure

{
  "params": {
    "msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341" -- random uuid
  },
  "request": {
    "name": "updated name of the forum",
    “groups” : [ // list of groups to be additionally created and associated with the forum. group id will be auto-generated using a combination of the forum id and a random string/number
	  { “permissions”: [“read”, “vote”], "applyToChildren": "true/false" }, // permissions to be given for each associated group
      { “permissions”: [“read”, “vote”, “post”, “topic”, “moderate”], "applyToChildren": "true/false" }
    ],
    “privileges”: [ // set of permissions to be given/updated for existing users or groups can also be provided
		{
			“permissions”: [“read”, “vote”, “post”, “topic”, “moderate”],
			“users”: [“list of sunbird user oidc ids”],
			“groups”: [“list of nodebb group ids”],
			"applyToChildren": "true/false, if these users/groups should be given same set of privileges in all the sub-forums"
		},
		{
			“permissions”: null, // if permissions is set as null, access to the given list of users/groups should be removed
			“users”: [“list of sunbird user oidc ids”],
			“groups”: [“list of nodebb group ids”],
			"applyToChildren": "true/false"
		}
    ],
    "children": [ // list of new sub-forums to be created
      {
        "name": "Name of the sub-forum", 
        "groups": [], // permissions for the sub-forum can be configured by associating groups or 
        "privileges": [] // giving privileges to existing users or groups
      }
    ]
  }
}

Response Structure

{
  "id": "api.discussions.forum.update",
  "ver": "1.0",
  "ets": "1600883199000",
  "params": {
    "resmsgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341"
    "msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341",
    "status": "successful",
  },
  "responseCode": "OK",
  "result": {
    “identifier”: “forum id”
  }
}

Fetch Forum API

API to get details of a forum for a given context.

Request Path: “/api/forum/v1/fetch”

Method:“POST”

Request Structure

{
  "params": {
    "msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341" -- random uuid
  },
  "request": {
    “context”: {
		“type”: “batch”,
		“identifier”: “batch id, e.g: 012232323223232”
    }
  }
}

Response Structure

{
  "id": "api.discussions.forum.fetch",
  "ver": "1.0",
  "ets": "1600883199000",
  "params": {
    "resmsgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341"
    "msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341",
    "status": "successful",
  },
  "responseCode": "OK",
  "result": {
  “forums”: [
    {
		“identifier”: “forum id”,
		“name”: “name of the forum”,
		“groups”: [ // list of groups which have access to the forum
	  		{
				“identifier”: “identifier of the nodebb group”,
				“permissions”: [“read”, “vote”, “post”, “topic”, “moderate”]
	  		}
		],
		“users”: [ // list of users who have access to the forum
	  		{
				“identifier”: “sunbird user oidc id”,
				“permissions”: [“read”, “vote”, “post”, “topic”, “moderate”]
	  		}
		],
		"children": [ // list of sub-forums
			{
				"identifier": "sub-forum id",
				"name": "name of the sub-forum",
				"groups": [], // list of groups which have access to the sub-forum
				"users": [] // list of users who have access to the sub-forum
			}
		]
    }
  ]
}

Read Forum API

API to get details of a forum by forum id.

Request Path: “/api/forum/v1/read/<forum_id>”

Method:“GET”

Response Structure

{
  "id": "api.discussions.forum.read",
  "ver": "1.0",
  "ets": "1600883199000",
  "params": {
    "resmsgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341"
    "msgid": "4f04da60-1e24-4d31-aa7b-1daf91c46341",
    "status": "successful",
  },
  "responseCode": "OK",
  "result": {
  “forums”: [
    {
		“identifier”: “forum id”,
		“name”: “name of the forum”,
		“groups”: [ // list of groups which have access to the forum
	  		{
				“identifier”: “identifier of the nodebb group”,
				“permissions”: [“read”, “vote”, “post”, “topic”, “moderate”]
	  		}
		],
		“users”: [ // list of users who have access to the forum
	  		{
				“identifier”: “sunbird user oidc id”,
				“permissions”: [“read”, “vote”, “post”, “topic”, “moderate”]
	  		}
		],
		"children": [ // list of sub-forums
			{
				"identifier": "sub-forum id",
				"name": "name of the sub-forum",
				"groups": [], // list of groups which have access to the sub-forum
				"users": [] // list of users who have access to the sub-forum
			}
		]
    }
  ]
}

API Security

API Token

All APIs (including NodeBB APIs) should be onboarded on to Sunbird API manager and appropriate ACLs should be configured for all the APIs. No API should be directly accessible.

All API requests should have a request header “authorization“ in which the API token should be passed:

-H 'authorization: Bearer {{api_token}}'

TODO: List the ACL - API mapping for all the APIs

User Auth Token

All Sunbird discussion APIs should have an additional security layer that validates the user’s access using the user token generated by keycloak. Keycloak token should be passed to the API using “x-authenticated-user-token“ header.

-H 'x-authenticated-user-token: {{keycloak_access_token}}'

API should check if the passed user token is valid
API should check if the user whose token is passed in the request has access to perform the required operation (e.g.: in Update Forum API, check if user has access to update the specific forum)

Discussions - API Design

Request & Response Envelopes

NodeBB APIs

Sunbird APIs

Create User API

Create Forum API

Update Forum API

Fetch Forum API

Read Forum API

API Security

API Token

User Auth Token

Related content