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: https://github.com/NodeBB/nodebb-plugin-write-api/blob/master/routes/v2/readme.md

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

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

Response Structure

Update Forum API

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

Method:“PATCH”

Request Structure

Response Structure

Fetch Forum API

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

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

Method:“POST”

Request Structure

Response Structure

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

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)