KBQuest CMS API

1. OBJECTIVE

By following this specification, EDU.INK technical team should be able to develop their own interfaces to achieve the following operations:

Popup message: to retrieve adhoc/important message when user visits the landing page of the school website.
News: allow WordPress server to import the latest news from EDU.INK.

2. Basics

2.1. Connection

The domain of the API is isfapi2.isf.edu.hk.

2.2. Response Format

The API returns data in json format. The format is:


{
  // The txID is a unique identifier of response message.
  // The identifier will be used during troubleshooting.
  "txID": "xxxxxx",
  "code": "xxxxxx", // return code
  "message": "xxxxxx", //status message
  "content": {
    // the actual business data
  }
}

When the code is D00000, the service execution is successful, and the content field returned by the HTTPS request contains the actual business data. When the code is not D00000, it indicates that the service execution is abnormal, and the content field will be empty.

2.3. Return Code

Code	Message
`D00000`	successful return
`D20000`	unknown exception
`D20001`	`{%s}` should not be empty
`D20002`	`{%s}` is invalid
`D20003`	timeout
`D20004`	siteID does not exist
`D20005`	email does not exist

3. API Specifications

User’s browser calls this API to retrieve a list of popup message to be displayed on the landing page of the website.

To add an alert the the popup message list, please check “Send popup message to website” in the edit screen.


Method: GET
URL: https://<API_DOMAIN>/kbquest/api/v1/popupmsg/check

Request Parameters As GET Query

Parameters	Type	Required	Description
`siteId`	String	Required	value MUST be set to `academy` or `pre-school`
`lang`	String	—	Language to display: `en-US`, `zh-HK`. If this parameter is not specified, `en-US` will be shown.

Examples

Example 1: Retrieve all popup messages visible to the website in default language (English).


GET
https://<API_DOMAIN>/api/v1/popupmsg/check?siteId=academy

Example 2: Retrieve all popup messages visible to the website in Chinese.


GET
https://<API_DOMAIN>/api/v1/popupmsg/check?siteId=academy
  &lang=zh-HK

Response Parameters

Parameter	Type	Required	Description
`msgTitle`	String	Required	The message title to display
`msgBody`	String	Required	Language to display: `en-US`, `zh-HK`. If this parameter is not specified, `en-US` will be shown.
`displayDate`	String	Required	DateTime format: YYYYMMDDhhmmss
`iconId`	String	—	Refer to the Icon ID table. If this parameter is not specified, no icon will be display.
`needConfirm`	String	—	Value: `confirm`, `Accept`. If this parameter is not specified, no button will be display.

Icon ID (Icon image will be provided by KBQuest):

2: Black rain signal 3: Typhoon-3 4: Typhoon-8-ne 5: Typhoon-8-se 6: Typhoon-8-sw 7: Typhoon-8-nw 8: Typhoon-9 9: Typhoon-10 10: Event Related

Example Success Response


{
  "txID": "xxxxxx",
  "code": "D00000",
  "message": "SUCCESS",
  "content": [{
    "msgTitle": "Message title here",
    "msgBody": "Message content here (HTML)",
    "displayDate": "20201231235900",
    "iconId": "1",
    "needConfirm": "confirm"
  },{
    "msgTitle": "Another message title here",
    "msgBody": "Message content here",
    "displayDate": "20201231235900"
  }]
}

Example Error Response

When siteId is empty:


{
  "txID": "2.22.1-2012081412/5c2a2/20210108162037",
  "code": "D20001",
  "message": "siteId should not be empty"
}

3.2. Retrieve News

WordPress calls this API to get news entries created/modified/removed.


Method: GET
URL: https://<API_DOMAIN>/kbquest/api/v1/news/check

Request Parameters As GET Query

Parameters	Type	Required	Description
`siteId`	String	Required	value MUST be set to `academy` or `pre-school`
`lang`	String	—	Language to display: `en-US`, `zh-HK`. If this parameter is not specified, `en-US` will be shown.
`lastSyncTime`	String	Required	Date format: YYYYMMDDhhmmss
`newsIDs`	String	—	Additional news to be retrieved regardless to the `lastSyncTime` parameter.

Examples

Example 1: Retrieve news entries that are published or deleted after 2020-12-31 23:59:59. All news entries in the school are retrieved regardless of unit / year / recipient settings.


GET
https://<API_DOMAIN>/api/v1/news/check?siteId=academy
  &lang=zh-HK
  &lastSyncTime=20201231235959

Example 2: Retrieve news entries that are published or deleted after 2020-12-31 23:59:59, *PLUS* news with ID 1001, 1002, and 1003.


GET
https://<API_DOMAIN>/api/v1/news/check?siteId=academy
  &lang=zh-HK
  &lastSyncTime=20201231235959
  &newsIDs=1001,1002,1003

Response Parameters

Parameter	Type	Required	Description
`newsList`	Object[]	Required	Array of news entries.
`newsList.newsId`	String	Required	News ID in EDU.INK system.
`newsList.newsTitle`	String	Required	News title.
`newsList.newsContent`	String	Required	News Content.
`newsList.newsDate`	String	Required	News date.
`newsList.newsDateTime`	String	Required	News date/time.
`newsList.mobileScreenImageUrl`	String	—	News cover image suitable to display on mobile/desktop (width: 1024px).
`newsList.thumbnailUrl`	String	—	News cover image in square thumbnail (200px by 200px).
`newsList.attachments`	Object[]	—	News attachments in JSON object array. See the `Attachment` schema below.
`delNewsIds`	String	Required	Array of news ID that are deleted.

`Attachment` schema:

Parameter	Type	Required	Description
`fileType`	String	Required	File MIME. One of the following: “image/png”, “image/jpeg”, “application/pdf”, “audio/mpeg”, “audio/mp3”, “video/mp4”
`fileSize`	Number	Required	Number of bytes. Suggest to use https://www.npmjs.com/package/pretty-bytes to convert it into human friendly format. Example: `703797 => "704 kB"`
`url`	String	Required	Public URL of the original file.
`thumbnailUrl`	String	Required	Square thumbnail (200px by 200px).
`mobileScreenImageUrl`	String	Required	Larger image for mobile/desktop (width: 1024px).
`imageWidth`	Number	(`fileType` is PNG or JPEG)	Original image width.
`imageHeight`	Number	(`fileType` is PNG or JPEG)	Original image height.
`imageDateTime`	String	(`fileType` is PNG or JPEG)	Original image date/time stamp. Extract from EXIF metadata if available from the original file.

Example Success Response


{
  "txID": "2.22.1-2012081412/5c2a2/20210108164244",
  "code": "D00000",
  "message": "SUCCESS",
  "content": {
    "newsList": [
      {
        "newsId": "117",
        "newsTitle": "KBQuest API Test 2 EN",
        "newsContent": "<div>KBQuest API Test 2 EN</div>",
        "newsDate": "20210108",
        "newsDateTime": "20210108080000",
        "mobileScreenImageUrl": "https://storage.googleapis.com/eduink-storage-2/isf2-files/school-public-files/fe5b8364.w1024.jpg",
        "thumbnailUrl": "https://storage.googleapis.com/eduink-storage-2/isf2-files/school-public-files/fe5b8364.w200h200.jpg",
        "attachments": []
      },
      {
        "newsId": "135",
        "newsTitle": "Stevie Awards Won on “ISF 15th Anniversary Celebrations”",
        "newsContent": "<div>&nbsp;The ISF Academy has won the Bronze Asia Pacific Stevie Awards in Innovation in the Use of Events for our series of 15th Anniversary Celebrations of The ISF Academy. As one of the world’s premier business awards, the Stevie Awards were created in 2002 to honor the achievements and positive contributions of organizations and working professionals.&nbsp;</div>",
        "newsDate": "20210129",
        "newsDateTime": "20210129080000",
        "thumbnailUrl": "https://storage.googleapis.com/eduink-storage-2/isf2-files/school-public-files/c5d13137.w200h200.jpeg",
        "mobileScreenImageUrl": "https://storage.googleapis.com/eduink-storage-2/isf2-files/school-public-files/c5d13137.w1024.jpeg",
        "attachments": [
          {
            "thumbnailUrl": "https://storage.googleapis.com/eduink-storage-2/isf2-files/school-public-files/a51f11c4.w200h200.jpeg",
            "mobileScreenImageUrl": "https://storage.googleapis.com/eduink-storage-2/isf2-files/school-public-files/a51f11c4.w1024.jpeg",
            "fileType": "image/jpeg",
            "fileSize": 115407,
            "imageWidth": 1280,
            "imageHeight": 640,
            "imageDateTime": "2021-01-28T07:12:28.147Z",
            "url": "https://storage.googleapis.com/eduink-storage-2/isf2-files/school-public-files/a51f11c4.jpeg"
          }
        ]
      },
    ],
    "delNewsIds": []
  }
}

Example Error Response

Missing lastSyncTime:


{
  "txID": "2.22.1-2012081412/5c2a2/20210108164646",
  "code": "D20001",
  "message": "lastSyncTime should not be empty"
}

KBQuest CMS API

1. OBJECTIVE

2. Basics

2.1. Connection

2.2. Response Format

2.3. Return Code

3. API Specifications

3.1. Retrieve Popup Message (a.k.a. Alerts)

Request Parameters As GET Query

Examples

Response Parameters

Example Success Response

Example Error Response

3.2. Retrieve News

Request Parameters As GET Query

Examples

Response Parameters

Attachment schema:

Example Success Response

Example Error Response

`Attachment` schema: