The Jolokia Api Server

(Generated by yarn build-api-doc.)

Version 0.1.1

This document contains a list of currently available apis that can be used by the activemq-artemis-self-provisioning plugin to get access to the management api of a broker instance via its jolokia endpoint.

How to add new apis to the src

The api server uses openapi to define its apis. All the apis are defined in the file openapi.yml.

To add a new api first open the openapi.yml and add a new api definition, for example:

/hello:
  get:
    description: hello api
    tags:
      - greeting
    operationId: hello
    parameters:
      - name: name
        required: false
        in: query
        description: The name of a caller
        schema:
          type: string
  responses:
    200:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DummyResponse'

With the above section added, you defined the new api under the path /hello and uses http GET method. It takes one optional parameter name of string type. The response contains json value and the structure is defined in /components/schemas/DummyResponse schema defined in the same file. The operationId represents the method name that implements the api.

Next step is add the implmentation.

Find a place to write your implementation. Your code should be placed in the src/api/controllers directory. Either create a new .ts file or use an existing one.

The following code shows a sample implementation:

export function hello(req: express.Request, res: express.Response): void {
  const name = req.query.name || 'stranger';
  const message = `Hello, ${name}!`;
  res.json({
    message: message,
    status: 'successful',
  });
}

That's it. A new api now is available under path /api/v1/hello.

Tip: You can consider using the swagger editor to edit the openapi.yml file.

For more information on how to write the api definition, please see openapi spec

Note: If you make changes to the openapi.yml, please run yarn build-api-doc to update the doc.

Update the generated endpoints for the frontend

After any change to the api, run yarn codegen to regenerate the endpoints for the frontend. If necessary update the code that is using the hooks to comply with your changes.

Path Table

Method	Path	Description
POST	/jolokia/login	The login api
GET	/brokers	retrieve the broker mbean
GET	/brokerDetails	broker details
GET	/readBrokerAttributes	read broker attributes
GET	/readAddressAttributes	read address attributes
GET	/readQueueAttributes	read queue attributes
GET	/readAcceptorAttributes	read acceptor attributes
GET	/readClusterConnectionAttributes	read cluster connection attributes
POST	/execClusterConnectionOperation	execute a cluster connection operation
GET	/checkCredentials	Check the validity of the credentials
POST	/execBrokerOperation	execute a broker operation
GET	/brokerComponents	list all mbeans
GET	/addresses	retrieve all addresses on broker
GET	/queues	list queues
GET	/queueDetails	retrieve queue details
GET	/addressDetails	retrieve address details
GET	/acceptors	list acceptors
GET	/acceptorDetails	retrieve acceptor details
GET	/clusterConnections	list cluster connections
GET	/clusterConnectionDetails	retrieve cluster connection details
GET	/api-info	the api info

Reference Table

Name	Path	Description
OperationRef	#/components/schemas/OperationRef
OperationArgument	#/components/schemas/OperationArgument
OperationResult	#/components/schemas/OperationResult
DummyResponse	#/components/schemas/DummyResponse
ApiResponse	#/components/schemas/ApiResponse
LoginResponse	#/components/schemas/LoginResponse
Address	#/components/schemas/Address
Acceptor	#/components/schemas/Acceptor
ClusterConnection	#/components/schemas/ClusterConnection
Queue	#/components/schemas/Queue
Broker	#/components/schemas/Broker
FailureResponse	#/components/schemas/FailureResponse
JavaTypes	#/components/schemas/JavaTypes
ComponentDetails	#/components/schemas/ComponentDetails
Signatures	#/components/schemas/Signatures
Signature	#/components/schemas/Signature
Attr	#/components/schemas/Attr
Argument	#/components/schemas/Argument
ComponentAttribute	#/components/schemas/ComponentAttribute
ExecResult	#/components/schemas/ExecResult

Path Details

[POST]/jolokia/login

Summary
The login api
Description
This api is used to login to a jolokia endpoint. It tries to get the broker mbean via the joloia url using the parameters passed in. If it succeeds, it generates a jwt token and returns
it back to the client. If it fails it returns a error. Once authenticated, the client can access the
apis defined in this file. With each request the client must include a valid jwt token in a http header named jolokia-session-id. The src will validate the token before processing a request is and rejects the request if the token is not valid.

RequestBody

application/json

{
  // identity of the broker instance, must in form of {cr-name}-{pod-ordinal}:{namespace}. For example ex-aao-0:test1
  brokerName: string;
  // The user name
  userName: string;
  // The password
  password: string;
  // The host name of the broker
  jolokiaHost: string;
  // either *http* or *https*
  scheme: string;
  // port number of jolokia endpoint
  port: string;
}

Responses

200 Success

application/json

{
  message: string
  status: string
  // The jwt token
  jolokia-session-id: string
}

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/brokers

Summary
retrieve the broker mbean
Description
Get the broker mbean
The return value is a one-element array that contains
the broker's mbean object name.

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  name: string;
}
[];

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/brokerDetails

Summary
broker details
Description
Get the broker details
The return value is a json object that contains
description of all the operations and attributes of the broker's mbean.
It is defined in ActiveMQServerControl.java

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  op: {
  }
  attr: {
  }
  class: string
  desc: string
}

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/readBrokerAttributes

Summary
read broker attributes
Description
Read values of broker attributes
The return value is a json array that contains
values of requested attributes of the broker's mbean. Note: to read multiple attributes, set it to names parameter
separated by commas, e.g. Version,Status.

Parameters(Query)

names?: string[]

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  request: {
    mbean: string
    attribute?: string
    type: string
  }
  error_type?: string
  error?: string
  timestamp?: number
  status: number
}[]

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/readAddressAttributes

Summary
read address attributes
Description
Read values of address attributes
The return value is a json array that contains
values of requested attributes of the addresses's mbean. Note: to read multiple attributes, set it to attrs parameter
separated by commas, e.g. RoutingTypes,Address.

Parameters(Query)

name: string;

attrs?: string[]

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  request: {
    mbean: string
    attribute?: string
    type: string
  }
  error_type?: string
  error?: string
  timestamp?: number
  status: number
}[]

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/readQueueAttributes

Summary
read queue attributes
Description
Read values of queue attributes
The return value is a json array that contains
values of requested attributes of the queue's mbean. Note: to read multiple attributes, set it to attrs parameter
separated by commas, e.g. RoutingTypes,Address.

Parameters(Query)

name: string;

address: string;

routing-type: string

attrs?: string[]

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  request: {
    mbean: string
    attribute?: string
    type: string
  }
  error_type?: string
  error?: string
  timestamp?: number
  status: number
}[]

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/readAcceptorAttributes

Summary
read acceptor attributes
Description
Read values of acceptor attributes
The return value is a json array that contains
values of requested attributes of the acceptor's mbean. Note: to read multiple attributes, set it to attrs parameter
separated by commas, e.g. RoutingTypes,Address.

Parameters(Query)

name: string;

attrs?: string[]

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  request: {
    mbean: string
    attribute?: string
    type: string
  }
  error_type?: string
  error?: string
  timestamp?: number
  status: number
}[]

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/readClusterConnectionAttributes

Summary
read cluster connection attributes
Description
Read values of cluster connection attributes
The return value is a json array that contains
values of requested attributes of the cluster connection's mbean. Note: to read multiple attributes, set it to attrs parameter
separated by commas, e.g. NodeID, Topology.

Parameters(Query)

name: string;

attrs?: string[]

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  request: {
    mbean: string
    attribute?: string
    type: string
  }
  error_type?: string
  error?: string
  timestamp?: number
  status: number
}[]

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[POST]/execClusterConnectionOperation

Summary
execute a cluster connection operation
Description
Invoke an operation of the cluster connection mbean It receives a POST request where the body
should have the operation signature and its args.
The return value is a one element json array that contains
return values of invoked operation along with the request info.

Parameters(Query)

name: string;

Headers

jolokia-session-id: string

RequestBody

application/json

{
  // The method signature
  signature: {
    name: string
    args: {
      type: enum[[Ljava.lang.Object;, [Ljava.lang.String;, [Ljava.util.Map;, [Ljavax.management.openmbean.CompositeData;, Object, boolean, double, int, java.lang.Boolean, java.lang.Integer, java.lang.Long, java.lang.Object, java.lang.String, java.util.Map, long, void]
      value: string
    }[]
  }
}

Responses

200 Success

application/json

{
  request: {
    mbean: string
    arguments?: string[]
    type: string
    operation: string
  }
  error_type?: string
  error?: string
  timestamp?: number
  status: number
}[]

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/checkCredentials

Summary
Check the validity of the credentials

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  message: enum[ok]
  status: enum[successful]
}

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[POST]/execBrokerOperation

Summary
execute a broker operation
Description
Invoke an operation of the broker mbean It receives a POST request where the body
should have the operation signature and its args.
The return value is a one element json array that contains
return values of invoked operation along with the request info.

Headers

jolokia-session-id: string

RequestBody

application/json

{
  // The method signature
  signature: {
    name: string
    args: {
      type: enum[[Ljava.lang.Object;, [Ljava.lang.String;, [Ljava.util.Map;, [Ljavax.management.openmbean.CompositeData;, Object, boolean, double, int, java.lang.Boolean, java.lang.Integer, java.lang.Long, java.lang.Object, java.lang.String, java.util.Map, long, void]
      value: string
    }[]
  }
}

Responses

200 Success

application/json

{
  request: {
    mbean: string
    arguments?: string[]
    type: string
    operation: string
  }
  error_type?: string
  error?: string
  timestamp?: number
  status: number
}[]

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/brokerComponents

Summary
list all mbeans
Description
List all broker components It retrieves and returns a list of all mbeans
registered directly under the broker managment domain.

Headers

jolokia-session-id: string

Responses

200 Success

application/json

string[]

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/addresses

Summary
retrieve all addresses on broker
Description
Get all addresses in a broker It retrieves and returns a list of all address mbeans

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  name: string;
  broker: {
    name: string;
  }
}
[];

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/queues

Summary
list queues
Description
Get all queues in a broker It retrieves and returns a list of all queue mbeans

Parameters(Query)

// If given only list the queues on this address
address?: string

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  name: string
  routing-type: string
  address: {
    name: string
    broker: {
      name: string
    }
  }
  broker:#/components/schemas/Broker
}[]

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/queueDetails

Summary
retrieve queue details
Description
Get details of a queue
The return value is a json object that contains
description of all the operations and attributes of the queue mbean. It is defined in QueueControl.java

Parameters(Query)

// the address name of the queue
addressName?: string

// the name of the queue
name: string;

// the routing type of the queue (anycast or multicast)
routingType: string;

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  op: {
  }
  attr: {
  }
  class: string
  desc: string
}

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/addressDetails

Summary
retrieve address details
Description
Get details of an address
The return value is a json object that contains
description of all the operations and attributes of the address mbean. It is defined in AddressControl.java

Parameters(Query)

// the address name
name: string;

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  op: {
  }
  attr: {
  }
  class: string
  desc: string
}

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/acceptors

Summary
list acceptors
Description
Get all acceptors in a broker It retrieves and returns a list of all acceptor mbeans

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  name: string;
  broker: {
    name: string;
  }
}
[];

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/acceptorDetails

Summary
retrieve acceptor details
Description
Get details of an acceptor
The return value is a json object that contains
description of all the operations and attributes of an acceptor mbean. It is defined in AcceptorControl.java

Parameters(Query)

// the acceptor name
name: string;

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  op: {
  }
  attr: {
  }
  class: string
  desc: string
}

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/clusterConnections

Summary
list cluster connections
Description
Get all cluster connections in a broker It retrieves and returns a list of all cluster connection mbeans

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  name: string;
  broker: {
    name: string;
  }
}
[];

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/clusterConnectionDetails

Summary
retrieve cluster connection details
Description
Get details of a connection cluster
The return value is a json object that contains
description of all the operations and attributes of a cluster connection mbean. It is defined in ClusterConnectionControl.java

Parameters(Query)

// the cluster connection name
name: string;

Headers

jolokia-session-id: string

Responses

200 Success

application/json

{
  op: {
  }
  attr: {
  }
  class: string
  desc: string
}

401 Invalid credentials

application/json

{
  status: enum[failed, error]
  message: string
}

500 Internal server error

application/json

{
  status: enum[failed, error]
  message: string
}

[GET]/api-info

Summary
the api info
Description
Show all exposed paths on the api server The return value is a json object that contains
description of all api paths defined in the api server.

Responses

200 Success

application/json

{
  message: {
    info: {
      name?: string
      description?: string
      version?: string
    }
    paths: {
      post?: string[]
      get?: string[]
    }
  }
  status?: enum[successful]
  // The jwt token
  jolokia-session-id?: string
}

References

#/components/schemas/OperationRef

{
  // The method signature
  signature: {
    name: string
    args: {
      type: enum[[Ljava.lang.Object;, [Ljava.lang.String;, [Ljava.util.Map;, [Ljavax.management.openmbean.CompositeData;, Object, boolean, double, int, java.lang.Boolean, java.lang.Integer, java.lang.Long, java.lang.Object, java.lang.String, java.util.Map, long, void]
      value: string
    }[]
  }
}

#/components/schemas/OperationArgument

{
  type: enum[[Ljava.lang.Object;, [Ljava.lang.String;, [Ljava.util.Map;, [Ljavax.management.openmbean.CompositeData;, Object, boolean, double, int, java.lang.Boolean, java.lang.Integer, java.lang.Long, java.lang.Object, java.lang.String, java.util.Map, long, void]
  value: string
}

#/components/schemas/OperationResult

{
  request: {
    mbean: string
    arguments?: string[]
    type: string
    operation: string
  }
  value: string
  timestamp: number
  status: number
}

#/components/schemas/DummyResponse

{
  message: enum[ok]
  status: enum[successful]
}

#/components/schemas/ApiResponse

{
  message: {
    info: {
      name?: string
      description?: string
      version?: string
    }
    paths: {
      post?: string[]
      get?: string[]
    }
  }
  status?: enum[successful]
  // The jwt token
  jolokia-session-id?: string
}

#/components/schemas/LoginResponse

{
  message: string
  status: string
  // The jwt token
  jolokia-session-id: string
}

#/components/schemas/Address

{
  name: string;
  broker: {
    name: string;
  }
}

#/components/schemas/Acceptor

{
  name: string;
  broker: {
    name: string;
  }
}

#/components/schemas/ClusterConnection

{
  name: string;
  broker: {
    name: string;
  }
}

#/components/schemas/Queue

{
  name: string
  routing-type: string
  address: {
    name: string
    broker: {
      name: string
    }
  }
  broker:#/components/schemas/Broker
}

#/components/schemas/Broker

{
  name: string;
}

#/components/schemas/FailureResponse

{
  status: enum[failed, error]
  message: string
}

#/components/schemas/JavaTypes

{
  "type": "string",
  "enum": [
    "[Ljava.lang.Object;",
    "[Ljava.lang.String;",
    "[Ljava.util.Map;",
    "[Ljavax.management.openmbean.CompositeData;",
    "Object",
    "boolean",
    "double",
    "int",
    "java.lang.Boolean",
    "java.lang.Integer",
    "java.lang.Long",
    "java.lang.Object",
    "java.lang.String",
    "java.util.Map",
    "long",
    "void"
  ]
}

#/components/schemas/ComponentDetails

{
  op: {
  }
  attr: {
  }
  class: string
  desc: string
}

#/components/schemas/Signatures

{
  ret?: enum[[Ljava.lang.Object;, [Ljava.lang.String;, [Ljava.util.Map;, [Ljavax.management.openmbean.CompositeData;, Object, boolean, double, int, java.lang.Boolean, java.lang.Integer, java.lang.Long, java.lang.Object, java.lang.String, java.util.Map, long, void]
  desc: string
  args: {
    name: string
    type:#/components/schemas/JavaTypes
    desc: string
  }[]
}[]

#/components/schemas/Signature

{
  ret?: enum[[Ljava.lang.Object;, [Ljava.lang.String;, [Ljava.util.Map;, [Ljavax.management.openmbean.CompositeData;, Object, boolean, double, int, java.lang.Boolean, java.lang.Integer, java.lang.Long, java.lang.Object, java.lang.String, java.util.Map, long, void]
  desc: string
  args: {
    name: string
    type:#/components/schemas/JavaTypes
    desc: string
  }[]
}

#/components/schemas/Attr

{
  desc: string
  rw: boolean
  type: enum[[Ljava.lang.Object;, [Ljava.lang.String;, [Ljava.util.Map;, [Ljavax.management.openmbean.CompositeData;, Object, boolean, double, int, java.lang.Boolean, java.lang.Integer, java.lang.Long, java.lang.Object, java.lang.String, java.util.Map, long, void]
}

#/components/schemas/Argument

{
  name: string
  type: enum[[Ljava.lang.Object;, [Ljava.lang.String;, [Ljava.util.Map;, [Ljavax.management.openmbean.CompositeData;, Object, boolean, double, int, java.lang.Boolean, java.lang.Integer, java.lang.Long, java.lang.Object, java.lang.String, java.util.Map, long, void]
  desc: string
}

#/components/schemas/ComponentAttribute

{
  request: {
    mbean: string
    attribute?: string
    type: string
  }
  error_type?: string
  error?: string
  timestamp?: number
  status: number
}

#/components/schemas/ExecResult

{
  request: {
    mbean: string
    arguments?: string[]
    type: string
    operation: string
  }
  error_type?: string
  error?: string
  timestamp?: number
  status: number
}

Files

api.md

Latest commit

History

api.md

File metadata and controls

The Jolokia Api Server

How to add new apis to the src

Update the generated endpoints for the frontend

Path Table

Reference Table

Path Details

[POST]/jolokia/login

RequestBody

Responses

[GET]/brokers

Headers

Responses

[GET]/brokerDetails

Headers

Responses

[GET]/readBrokerAttributes

Parameters(Query)

Headers

Responses

[GET]/readAddressAttributes

Parameters(Query)

Headers

Responses

[GET]/readQueueAttributes

Parameters(Query)

Headers

Responses

[GET]/readAcceptorAttributes

Parameters(Query)

Headers

Responses

[GET]/readClusterConnectionAttributes

Parameters(Query)

Headers

Responses

[POST]/execClusterConnectionOperation

Parameters(Query)

Headers

RequestBody

Responses

[GET]/checkCredentials

Headers

Responses

[POST]/execBrokerOperation

Headers

RequestBody

Responses

[GET]/brokerComponents

Headers

Responses

[GET]/addresses

Headers

Responses

[GET]/queues

Parameters(Query)

Headers

Responses

[GET]/queueDetails

Parameters(Query)

Headers

Responses

[GET]/addressDetails

Parameters(Query)

Headers

Responses

[GET]/acceptors

Headers

Responses

[GET]/acceptorDetails

Parameters(Query)

Headers

Responses

[GET]/clusterConnections

Headers