MCN Launch Pad Web Access - REST API Documentation

Models Used in this REST API

Page

interface Page
{
    pageId: string;
    name: string;
    macro: string;
    categories: Category[];
    toolbarButtons: ActionLink[];
}

Category

interface Category
{
    categoryId: string;
    name: string;
    macro: string;
    actionLinks: ActionLink[];
}    

ActionLink

interface ActionLink {
    actionLinkId: string;
    caption: string;
    searchText: string | null;  // This field is always 'null' when it's used as a Toolbar Button.
    icon: string;
    action: string;
    macro: string;
    isPinned: boolean | null;   // This field is always 'null' when it's used as a Toolbar Button.
}

WebIcon

interface WebIcon
{
    name: string,
    iconFile: string
}

SseEvent

interface SseEvent
{
    type: string;
    data: string;
}

Depending on the type, data may be a Base64Encoded JSON Object.

ErrorMessage

For receiving or sending messages.

interface ServerMessage
{
    type: string;
    message: string;
}

ConsoleVariable

interface ConsoleVariable
{
    name: string;
    value: string;
    oldValue: string;       // Used in the SSE Event. This can be ignored in the API requests.
    type: string;
    flags: string;
}

Because of the translation limitation for variable types between Java and JavaScript, values will always be strings. It's up to the JavaScript logic to convert the value into the correct JavaScript data type, based on the provided "type" field. This type can be one of the following:

• boolean
• byte
• short
• integer
• long
• float
• double
• string

In case the value is a complex data type, the type will be "json", and the string will be a Base64-encoded JSON object. The object contains the complex data type. This can be a byte array or some other form of object.

When requesting a variable from the server, you should check the reference manual to check the data type of the variable.

Page Manager Requests

Create a Page

This request creates a page.

The Request

• URL: /api/page/create
• Method: POST
• Content-Type: application/json
• Body: Page object as a JSON String. The following fields are required:
  • name
  • macro (It can be an empty string)

Expected Returns

• Code HTTP-201 - Object created
  • This means the page has been created.
• Code HTTP-409 - Conflict
  • This means that the name of the page already exists and therefore the creation of this object has been rejected.
• Code HTTP-500 - Internal Server Error
  • This means that something went wrong while creating the page. You should check the server logs for more information, or check the provided error message sent by the server.

In the case of HTTP-201, the server will return the Page object itself as JSON, with a new pageId.

Read a Page (or Pages)

This request will retrieve pages from the server.

The Request

• URL: /api/page/read/ <* | <:pageId>>
  • In case of /*, the server will return all pages as an array.
  • in case of :pageId, the server will just return the page matching that ID.
• Method: GET
• Content-Type: application/json

Expected Returns

• Code HTTP-200 - OK:
  • The server will return either a Page object or an array of page objects, depending on the request.
• Code HTTP-404 - Not Found:
  • The requested pageId was not found on the server.
• Code HTTP-405 - Method Not Allowed:
  • The method used on this URL is not allowed. (Only use the GET method)
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while retrieving the page(s). You should check the server logs for more information, or check the provided error message sent by the server.

Update a Page

This will update a page on the server.

The Request:

• URL: /api/page/update
• Method: PUT
• Content-Type: application/json
• Body: The JSON object of the updated page. The following fields are required:
  • pageId (This is the only field that you can't modify, because it also serves as an identifier)
  • name
  • macro

You do not need to add the categories or toolbar buttons to the JSON object, as those fields will be ignored anyway.

Expected Returns

• Code HTTP-201 - Content Created:
  • This means that the page was updated with the new values.
  • The server will also return the page object as JSON with the modified values.
• Code HTTP-404 - Not Found:
  • The pageId inside the provided object does not exist on the server.
• Code HTTP-409 - Conflicting Content
  • You can't set the name of the page to a name that is already in use by another page.
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while updating the page. You should check the server logs for more information, or check the provided error message sent by the server.

Delete a Page

Deletes a page.

The Request

• URL: /api/page/delete/ <:pageId>
• Method: DELETE
• Content-Type: application/json

Expected Returns

• Code HTTP-200 - OK:
  • This signals that the page has been deleted, and there is no content to return.
• Code HTTP-204 - No Content:
  • The provided :pageId does not exist, so no content, as it doesn't really matter.
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while deleting the page. You should check the server logs for more information, or check the provided error message sent by the server.

Category Manager Requests

Create a Category

This request creates a category.

The Request

• URL: /api/category/create/:pageId - The pageId is required to know on which page the category needs to be created.
• Method: POST
• Content-Type: application/json
• Body: Category object as a JSON String. The following fields are required:
  • name
  • macro (It can be an empty string)

Expected Returns

• Code HTTP-201 - Object created
  • This means the category has been created.
• Code HTTP-404 - Not Found
  • This means that the provided pageId doesn't exist.
• Code HTTP-409 - Conflict
  • This means that the name of the category already exists on the page and therefore the creation of this object has been rejected.
• Code HTTP-500 - Internal Server Error
  • This means that something went wrong while creating the category. You should check the server logs for more information, or check the provided error message sent by the server.

In the case of HTTP-201, the server will return the Category object itself as JSON, with a new categoryId.

Read a Category (or Categories)

This request will retrieve categories from the server.

The Request

• URL: /api/category/read/ :categoryId | /api/category/read/page:pageId
  • The first request is for retrieving one specific category; the second request is to retrieve the categories on a page.
• Method: GET
• Content-Type: application/json

Expected Returns

• Code HTTP-200 - OK:
  • The server will return either a Category object or an array of Category objects, depending on the request.
• Code HTTP-404 - Not Found:
  • The requested :categoryId or :pageId was not found on the server.
• Code HTTP-405 - Method Not Allowed:
  • The method used on this URL is not allowed. (Only use the GET method)
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while retrieving the category or categories. You should check the server logs for more information, or check the provided error message sent by the server.

Update a Category

This will update a category on the server.

The Request:

• URL: /api/category/update
• Method: PUT
• Content-Type: application/json
• Body: The JSON object of the updated category. The following fields are required:
  • categoryId (This is the only field that you can't modify, because it also serves as an identifier)
  • name
  • macro

You do not need to add the action links to the JSON object, as these fields will be ignored anyway.

Expected Returns

• Code HTTP-201 - Content Created:
  • This means that the category was updated with the new values.
  • The server will also return the category object as a JSON with the modified values.
• Code HTTP-404 - Not Found:
  • The categoryId inside the provided object does not exist on the server.
• Code HTTP-409 - Conflicting Content
  • You can't set the name of the category to a name that is already in use by another category.
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while updating the category. You should check the server logs for more information, or check the provided error message sent by the server.

Delete a Category

Deletes a category.

The Request

• URL: /api/category/delete/ <:categoryId>
• Method: DELETE
• Content-Type: application/json

Expected Returns

• Code HTTP-200 - OK:
  • This signals that the category has been deleted, and there is no content to return.
• Code HTTP-204 - No Content:
  • The provided :categoryId does not exist, so no content, as it doesn't really matter.
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while deleting the category. You should check the server logs for more information, or check the provided error message sent by the server.

ActionLink Manager Requests

Create an ActionLink

This request creates an Action Link.

The Request

• URL: /api/actionlink/create/:categoryId - The :categoryId is required to know which category the Action Link needs to be created for.
• Method: POST
• Content-Type: application/json
• Body: Action Link object as a JSON String. The following fields are required:
  • caption
  • searchText
  • icon
  • action
  • macro

The isPinned field (together with the actionLinkId) will be ignored.

Expected Returns

• Code HTTP-201 - Object created
  • This means the Action Link has been created.
• Code HTTP-404 - Not Found
  • This means that the provided categoryId doesn't exist.
• Code HTTP-409 - Conflict
  • This means that the caption of the Action Link already exists on the category, and therefore the creation of this object has been rejected.
• Code HTTP-500 - Internal Server Error
  • This means that something went wrong while creating the Action Link. You should check the server logs for more information, or check the provided error message sent by the server.

In the case of HTTP-201, the server will return the Action Link object itself as JSON, with a new actionLinkId.

Read an Action Link (or Action Links)

This request will retrieve Action Links from the server.

The Request

• URL: /api/actionlink/read/:actionLinkId | /api/actionlink/read/category:categoryId
  • The first request is for retrieving one specific Action Link, the second request is to retrieve the ActionLinks on a Category.
• Method: GET
• Content-Type: application/json

Expected Returns

• Code HTTP-200 - OK:
  • The server will return either an ActionLink object or an array of ActionLink objects, depending on the request.
• Code HTTP-404 - Not Found:
  • The requested :actionLinkId or :categoryId was not found on the server.
• Code HTTP-405 - Method Not Allowed:
  • The method used on this URL is not allowed. (Only use the GET method)
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while retrieving the Action Link(s). You should check the server logs for more information, or check the provided error message sent by the server.

Update an Action Link

This will update an Action Link on the server.

The Request:

• URL: /api/actionLink/update
• Method: PUT
• Content-Type: application/json
• Body: The JSON object of the updated Action Link. The following fields are required:
  • actionLinkId (This is the only field that you can't modify, because it also serves as an identifier)
  • caption
  • searchText
  • icon
  • action
  • macro

The field for isPinned will be ignored, as this field is set with the set-pinned request.

Expected Returns

• Code HTTP-201 - Content Created:
  • This means that the Action Link was updated with the new values.
  • The server will also return the Action Link object as JSON with the modified values.
• Code HTTP-404 - Not Found:
  • The actionLinkId inside the provided object does not exist on the server.
• Code HTTP-409 - Conflicting Content
  • You can't set the caption of the Action Link to a caption that is already in use by another Action Link.
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while updating the Action Link. You should check the server logs for more information, or check the provided error message sent by the server.

Delete an Action Link

Deletes an Action Link.

The Request

• URL: /api/actionlink/delete/ <:actionLinkId>
• Method: DELETE
• Content-Type: application/json

Expected Returns

• Code HTTP-200 - OK:
  • This signals that the Action Link has been deleted, and there is no content to return.
• Code HTTP-204 - No Content:
  • The provided :actionLinkId does not exist, so no content, as it doesn't really matter.
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while deleting the Action Link. You should check the server logs for more information, or check the provided error message sent by the server.

Toolbar Manager Requests

Create a Toolbar Button

This request creates a Toolbar Button on a page.

Note: The model ActionLinkis used for the Toolbar Button. Even though both Action Links and Toolbar Buttons share the same Model, they are different components on the UI, and some fields are ignored for the Toolbar Button:

• searchText
• isPinned

You can safely omit these fields from your requests. The server will also use the ActionLink model in its responses, but these fields will always be null.

The Request

• URL: /api/toolbar-button/create/:pageId - The :pageId is required to know on which page the Toolbar Button needs to be created.
• Method: POST
• Content-Type: application/json
• Body: ActionLink object as a JSON String. The following fields are required:
  • caption
  • icon
  • action
  • macro

Expected Returns

• Code HTTP-201 - Object created
  • This means the Toolbar Button has been created.
• Code HTTP-404 - Not Found
  • This means that the provided pageId doesn't exist.
• Code HTTP-409 - Conflict
  • This means that the caption of the Toolbar Button already exists on the page, and therefore the creation of this object has been rejected.
• Code HTTP-500 - Internal Server Error
  • This means that something went wrong while creating the Toolbar Button. You should check the server logs for more information, or check the provided error message sent by the server.

In the case of HTTP-201, the server will return the Toolbar Button object itself as JSON, with a new actionLinkId.

Read a Toolbar Button (or Toolbar Buttons)

This request will retrieve Toolbar Buttons from the server.

The Request

• URL: /api/toolbar-button/read/:actionLinkId | /api/toolbar-button/read/page:pageId
  • The first request is for retrieving one specific Toolbar Button, the second request is to retrieve the ActionLinks on a Category.
• Method: GET
• Content-Type: application/json

Expected Returns

• Code HTTP-200 - OK:
  • The server will return either an ActionLink object or an array of ActionLink objects, depending on the request.
• Code HTTP-404 - Not Found:
  • The requested :actionLinkId or :pageId was not found on the server.
• Code HTTP-405 - Method Not Allowed:
  • The method used on this URL is not allowed. (Only use the GET method)
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while retrieving the Toolbar Button(s). You should check the server logs for more information, or check the provided error message sent by the server.

Update a Toolbar Button

This will update a Toolbar Button on the server.

The Request:

• URL: /api/toolbar-button/update
• Method: PUT
• Content-Type: application/json
• Body: The JSON object of the updated Toolbar Button. The following fields are required:
  • actionLinkId (This is the only field that you can't modify, because it also serves as an identifier)
  • caption
  • icon
  • action
  • macro

Expected Returns

• Code HTTP-201 - Content Created:
  • This means that the Toolbar Button was updated with the new values.
  • The server will also return the Toolbar Button object as JSON with the modified values.
• Code HTTP-404 - Not Found:
  • The actionLinkId inside the provided object does not exist on the server.
• Code HTTP-409 - Conflicting Content
  • You can't set the caption of the Toolbar Button to a caption that is already in use by another Toolbar Button.
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while updating the Toolbar Button. You should check the server logs for more information, or check the provided error message sent by the server.

Delete a Toolbar Button

Deletes a Toolbar Button.

The Request

• URL: /api/toolbar-button/delete/ <:actionLinkId>
• Method: DELETE
• Content-Type: application/json

Expected Returns

• Code HTTP-200 - OK:
  • This signals that the Toolbar Button has been deleted, and there is no content to return.
• Code HTTP-204 - No Content:
  • The provided :actionLinkId does not exist, so no content, as it doesn't really matter.
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while deleting the Toolbar Button. You should check the server logs for more information, or check the provided error message sent by the server.

Pin or Un-pin Action Links to the Favorites Bar

This feature may not exist in future releases, as it might be more interesting to manage pinned items in the UI client itself using Local Storage, rather than on the server... (Event though the Server is also part of the client...)

Pin or Unpin an Action Link

The Request

• URL: /api/set-pinned/:actionLinkId/true|false
• Method: PUT
• Content-Type: application/json
• Body: no-content required. All the information is already in the Url.

Expected Returns

• Code HTTP-200 - OK:
  • This signals that the pin or unpin action was done.
  • Also returns the ActionLink as JSON.
• Code HTTP-400 - Bad Request:
  • This indicates a malformed URI. Make sure your sending a correct URI. Examples:
    • /api/set-pinned/:AGID_1234567_1/true
    • /api/set-pinned/:AGID_1234567_1/false
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong while (un-)pinning the action link. You should check the server logs for more information, or check the provided error message sent by the server.

Console Variables

Sometimes you need to retrieve or set console variables. These requests will do that for you.

Retrieving a Console Variable

The Request:

• URL: /api/console-variable/ <* | :varname>
  • Providing * will retrieve all console variables as an array of ConsoleVariable.
  • Providing :varname will only get that specific variable.
• Method: GET
• Content-Type: application/json

Expected Returns

• Code HTTP-200 - OK:
  • It will also give you the ConsoleVariable as a JSON or an array, depending on the request.
• Code HTTP-400 - Bad Request
  • Malformed URI, or invalid WebConsoleVariable JSON in the body.
• Code HTTP-404 - Not Found:
  • When the requested console variable is not found.
• Code HTTP-405 - Method Not Allowed
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong with this request. You should check the server logs for more information, or check the provided error message sent by the server.

Setting a Console Variable

The Request:

• Url: /api/console-variable
• Method: PUT
• Content-Type: JSON
• Body: The ConsoleVariable object

Note: Only the value of the variable can be modified. If any other field is changed, the request will be rejected with an HTTP-403.

Expected Returns

• Code HTTP-200 - OK:
  • It will also give you the updated ConsoleVariable as JSON.
• Cpde HTTP-403 - Forbidden:
  • This happens when:
    • You tried to modify not only the value, but also another field, like the type or the flags.
    • When the variable is a read-only variable. ('w' or the 'write-flag' is not present)
• Code HTTP-404 - Not Found:
  • When the console variable name is not found.
• Code HTTP-405 - Method Not Allowed
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong with this request. You should check the server logs for more information, or check the provided error message sent by the server.

SSE Event

When a console value is changed, the console will also fire an SSE event:

{
    "type": "convar",
    "data": "base64:<Base64-Encoded ConsoleVariable JSON Object>"
}

More about SSE events in the SSE Event Documentation.

Running a Command on the Console

You can request to run a command on the JCIPS console. Use the following request to do so.

The Model used here is the ServerMessage model with the type set to 'command' and the message set to the Base64-encoded command string.

An example:

let command = "base64:" + base64encode('ECHO "Hello World"');
// You can also send the command as plain text:
//     let command = "ECHO \"Hello World\")

let ServerMessage = { 
    type: "command",
    message: command
}

Request:

• Url: /api/run
• Method: POST
• Content-Type: application/json
• Body: ServerMessage as JSON

Expected Returns

• Code: HTTP-200 - OK:
  • The command executed successfully. The server will also respond with a ServerMessage, with the message set to the last output of the console.
• Code: HTTP-400 - Bad Request
• Code: HTTP-403 - Forbidden:
  • The client is not allowed to run commands on the JCIPS console
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong with this request. You should check the server logs for more information or check the provided error message sent by the server.

Evaluating Macros

Macros are JavaScript evaluations. You can do them on the client, or you can request the JCIPS console to evaluate it for you.

To evaluate, you need to use the ServerMessage model to form the request, and the server will also respond with a ServerMessage, within the message, the result of the evaluation.

The Request:

• Url: /api/evaluate
• Method: POST
• Content-Type: application/json
• Body: ServerMessage as JSON

Expected Returns:

• Code: HTTP-200 - OK:
  • The result of the evaluation is in the ServerMessage.message field.
• Code: HTTP-403 - Forbidden:
  • The client is not allowed to perform macro evaluations on the JCIPS console
• Code HTTP-500 - Internal Server Error:
  • This means that something went wrong with this request. You should check the server logs for more information, or check the provided error message sent by the server.