BlueSpice knowledge base API

The Easy8 knowledge base is a BlueSpice wiki connected to Easy8 through the blue_spice plugin (plugins/easyproject/easy_plugins/blue_spice). Use the Postman files described below to test the Easy8-specific API calls of the wiki.

Wiki API

Most requests are standard MediaWiki API requests, documented at mediawiki.org. Each knowledge base also serves its own API at <kb-url>/w/api.php. Use it to understand requests and responses when something does not work or the API has changed.

Postman testing

Use Postman to inspect the responses of a knowledge base. The docs/files/postman folder contains two files.

1. bluespice 4.4.0.postman_environment.json: the environment variables the calls need.

   • kb-url: address of your knowledge base, taken from the KB deployment.
   • client_id, client_secret: found in the same place as the URL.
   • access_token: obtained with the Get access token call below.
   • username: login of the user you call the API as (usually the one you are logged in as in Easy8).

   To import it, open Environments in Postman, click Import and select the file. Then activate the environment (the tick icon shown when you hover over it).

2. Blue Spice.postman_collection.json: the collection of API calls. Each call has three tabs to know:

   • Auth: most calls need the access_token.
   • Headers: rarely need changes.
   • Body: some calls need data here, for example client_id and client_secret.

The most important calls:

POST Get access token: authorises the user to the KB. Call it first; the returned access_token is used in the Auth tab of most other calls.

GET References: lists the articles connected to a task. Parameters:

• type: for example issues
• id: the task ID

PUT Add Reference: connects a KB article to a task. Keep this body structure:

{
    "references": {
        "entityType": "Issue",
        "entityId": "778",
        "pagename": "Check_%2B_verify_url_encoded_titles"
    }
}

DELETE Reference: removes the article reference from the task.

PUT Sync groups: updates the user's permissions in the KB, which decide whether the user has access to it. Easy8 sends the same request (/w/rest.php/easy/sync_groups/<login>) from the update permissions section of the BlueSpice settings (/blue_spice/settings).