Version 2021

Project Administration

The following sequence of REST API requests allows an administrator to manage project distribution and configuration:

  1. Log In

    POST /auth/login

  2. Get Information about Nodes and Projects with Current Status

    GET /api/monitors/iServer/nodes

  3. Update Properties for a Specific Project

    PATCH /api/monitors/iServer/nodes/{nodeName}/projects/{projectId}

  4. Get Update Information About Projects for a Node

    GET /api/monitors/iServer/nodes

  5. Log Out

    POST /api/logout

Log In

End Point: POST /api/auth/login

This endpoint allows the caller to authenticate with the MicroStrategy REST Server. Provide the information used to create the session in the body of the request. In this example, you use standard authentication so you need to provide username, password, and loginMode (which specifies the authentication mode to use). If you omit an optional field, the REST Server uses the default value. If the call is successful, the resulting response returns a status code of 204 and a response header containing X-MSTR-AuthToken, the authorization token that will be used by subsequent requests.

Sample Request

  • Request body:

    {
  "username": "administrator",
  "password": "yourPassword",
  "loginMode": 1
}

  • Curl:

    curl -X POST "https:// demo.microstrategy.com/MicroStrategyLibrary/api/auth/login" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"username\":\"administrator\",\"password\":\"yourPassword\",\"loginMode\":1}"

  • Response header:

    cache-control: no-cache, no-store, max-age=0, must-revalidate 
 date: Mon, 28 Oct 2019 17:38:15 GMT 
 expires: 0 
 pragma: no-cache 
 x-mstr-authtoken: f34qc7evsntsks0qe6hfcgt0ur
  • Response code: 204 (Success: No Content)

Get Information about Nodes and Projects with Current Status

End Point: GET /api/monitors/iServer/nodes

This end point includes basic information, run time state, and information for the projects on each node. You specify an authorization token in the request header which you will get from POST /api/auth/login used during Log In.

You can also use filter option either on project id or node name or both to get specific information in response. This filed is optional.

You can expect the following statuses of the project to be returned with respect to the nodes: unloaded, loaded, exec_idle, request_idle, full_idle, wh_exec_idle, partial_idle, unloaded_pending, loaded_pending.

This operation requires the “Monitor cluster” privilege.

  • Request Parameter:

    • X-MSTR-AuthToken: Authorization Token
    • projects.id: Project Id (optional)
    • Name: Node Name (optional)

  • Curl:

    curl -X GET "https://demo.microstrategy.com/MicroStrategyLibrary/api/monitors/iServer/nodes" -H "accept: application/json" -H "X-MSTR-AuthToken: s664q0cqjergslaj4vfpnneb3m"

  • Response body:

    {
  "nodes": [
    {
      "name": "env-160560laio1use1",
      "port": 34952,
      "status": "running",
      "load": 1,
      "projects": [
        {
          "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754",
          "name": "MicroStrategy Tutorial",
          "status": "unloaded"
        },
        {
          "id": "B3FEE61A11E696C8BD0F0080EFC58F44",
          "name": "Hierarchies Project",
          "status": "loaded"
        }
      ],
      "default": true
    },
    {
      "name": "env-160560laio2use1",
      "port": 34952,
      "status": "running",
      "load": 0,
      "projects": [
        {
          "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754",
          "name": "MicroStrategy Tutorial",
          "status": "loaded"
        },
        {
          "id": "B3FEE61A11E696C8BD0F0080EFC58F44",
          "name": "Hierarchies Project",
          "status": "unloaded"
        }
      ]
    }
  ]
}
  • Response code: 200 (Success: OK)

To apply a filter on project id and node name, you can use the filter option of this api.

  • Curl:

    curl -X GET "https:// demo.microstrategy.com/MicroStrategyLibrary/api/monitors/iServer/nodes?projects.id=B7CA92F04B9FAE8D941C3E9B7E0CD754&name=env-160560laio1use1" -H "accept: application/json" -H "X-MSTR-AuthToken: 8jf3gkobqcdsljm8i3kio7nqc3"

  • Response body:

    {
  "nodes": [
    {
      "name": "env-160560laio1use1",
      "port": 34952,
      "status": "running",
      "load": 1,
      "projects": [
        {
          "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754",
          "name": "MicroStrategy Tutorial",
          "status": "unloaded"
        }
      ],
      "default": true
    }
  ]
}

Update Properties for a Specific Project

End Point: PATCH /api/monitors/iServer/nodes/{nodeName}/projects/{projectId}

You obtain the authorization token from POST /api/auth/login. You pass the authorization token in the request header. You obtain cluster node name and project id from GET /monitors/iServer/nodes.

Currently, we accept the following project status values for status path and replace operations: loaded, unloaded, request_idle, exec_idle, wh_exec_idle, partial_idle, full_idle.

This API will accept the request and start processing to execute based on the request submitted.

This operation requires the "Load and Unload project" and "Idle and Resume project" privileges.

  • Request parameters:

    • X-MSTR- AuthToken: Authorization Token
    • nodeName: Node Name
    • projectId: Project Id

  • Request body:

    {
  "operationList": [
    {
      "op": "replace",
      "path": "/status",
      "value": "loaded"
    }
  ]
}

  • Curl:

    curl -X PATCH " https:// demo.microstrategy.com/MicroStrategyLibrary/api/monitors/iServer/nodes/env-160560laio1use1/projects/B7CA92F04B9FAE8D941C3E9B7E0CD754" -H "accept: application/json" -H "X-MSTR-AuthToken: jal5uua4uo6gfag1vivmadag17" -H "Content-Type: application/json" -d "{\"operationList\":[{\"op\":\"replace\",\"path\":\"/status\",\"value\":\"loaded\"}]}"

  • Response body:

    {
  "project": {
    "name": "MicroStrategy Tutorial",
    "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754",
    "status": "pending"
  }
}
  • Response code: 202 (Accepted)

  • Error Handling:

    1. Invalid operation name

      {
  "code": "ERR006",
  "message": "Invalid JSON body. Cannot construct instance of `com.microstrategy.rest.model.iserver.PatchOperator`, problem: Invalid patch operations",
  "ticketId": "8ba0b99f09b14440b0b31a066cdb2678"
}

    2. Valid operation name but not valid for status path. To change the project status, the "replace" operation is allowed.

      {
 "code": "ERR006",
 "message": "Please validate operation type or value. Input value can not be
'add' as the Status in the given project.",
 "ticketId": "c1e816c9d2f44b13818319a7f4547bbe"
}

    3. No privileges

      • If the user does not have load and unload project privilege:

        {
  "code": "ERR014", 
 “IserverCode”: -2147213784,
 "message": "You do not have Load and unload project privilege(s) to perform the task.",
  "ticketId": "8ba0b99f09b14440b0b31a066cdb2678"
}

      • If the user does not have Idle and resume Project privilege:

        { 
"code": "ERR014", 
“IserverCode”: -2147213784, 
"message": "You do not have Load and unload project privilege(s) to perform the task.", 
"ticketId": "8ba0b99f09b14440b0b31a066cdb2678" 
}

    4. Invalid operation name

      {
  "code": "ERR006",
  "message": "xyz is not valid value to change project status. Valid values are loaded, unloaded, request_idle, exec_idle, partial_idle, wh_exec_idle, full_idle",
  "ticketId": "c98e0e6208a74dfda8cedee74925bfbb"
}

Get Update Information About Projects for a Node

End Point: GET /api/moniotrs/iServer/nodes

In the example above, the project status of “MicroStrategy Tutorial” was changed from unloaded to loaded on the cluster node named env-160560laio1use1. You can view the updated status through this API. Here, you can use the filter option on project id “B7CA92F04B9FAE8D941C3E9B7E0CD754” and/or on node name “env-160560laio1use1” to get information about the node.

  • Curl:

    curl -X GET "https:// demo.microstrategy.com/MicroStrategyLibrary/api/monitors/iServer/nodes?projects.id=B7CA92F04B9FAE8D941C3E9B7E0CD754&name=env-160560laio1use1" -H "accept: application/json" -H "X-MSTR-AuthToken: jal5uua4uo6gfag1vivmadag17"

  • Request body:

    {
  "nodes": [
    {
      "name": "env-160560laio1use1",
      "port": 34952,
      "status": "running",
      "load": 1,
      "projects": [
        {
          "id": "B7CA92F04B9FAE8D941C3E9B7E0CD754",
          "name": "MicroStrategy Tutorial",
          "status": "loaded"
        }
      ],
      "default": true
    }
  ]
}

Log Out

End Point: POST /api/auth/logout

This endpoint allows the caller to log out for the authenticated user with the MicroStrategy REST Server. In this example, you close the active user session by providing the authorization token, X-MSTR-AuthToken, generated by POST /auth/login. If the call is successful, the resulting response returns the status code 204.

  • Curl:

    curl -X POST "https:// demo.microstrategy.com/MicroStrategyLibrary/api/auth/logout" -H "accept: application/json" -H "X-MSTR-AuthToken: c8afkjurl1r9qk2k7puj2hs9cu"
  • Response Code: 204 (Accepted)