

Using the Management API

The Management API of WSO2 Micro Integrator is an internal REST API, which was introduced to substitute the admin services that were available in WSO2 EI 6.x.x.

The Micro Integrator CLI and the Micro Integrator dashboard communicates with this service to obtain administrative information of the server instance. If you are not using the dashboard or the CLI, you can directly access the resources of the management API by following the instructions given below.

Enabling the management API

The management API is disabled in the Micro Integrator by default. You can enable it when you start your Micro Integrator instance by passing the following system property:

-DenableManagementApi

Note that the default address is https://localhost and the port is 9164.

• When you run the Micro Integrator on Docker, start your Docker container by passing the enableManagementApi system property:

  docker run -p 8290:8290 -p 9164:9164 -e JAVA_OPTS="-DenableManagementApi=true" <Docker_Image_Name>

• When you run the Micro Integrator on a VM, use the following command to enable the enableManagementApi system property:

  sh micro-integrator.sh -DenableManagementApi

• The Management API is enabled for the embedded Micro Integrator in WSO2 Integration Studio by default.

Securely invoking the API

The management API is secured using JWT authentication by default. When you directly access the management API, you must first acquire a JWT token with your valid username and password.

Before you begin

Note the following:

• Your user name and password should already exist in the user store of the management API.
• By default, the file based user store is enabled in the internal-apis.xml file. However, if you have switched to TOML configurations (in the deplyment.toml file), you must manually enable the user store.

See Securing the Management API for instructions.

Getting a JWT token

Follow the steps given below to acquire the JWT token.

1. First, encode your username:password in Basic Auth format (encoded in base64). For example, use the default admin:admin credentials.
2. Invoke the /login resource of the API with your encoded credintials as shown below.

   curl -X GET "https://localhost:9164/management/login" -H "accept: application/json" -H "Authorization: Basic YWRtaW46YWRtaW4=" -k -i

3. The API will validate the authorization header and provide a response with the JWT token as follows:

   { 
      "AccessToken":"%AccessToken%"
   }

Invoking an API resource

You can now use this token when you invoke a resource.

Info

When the default JWT security handler is engaged, all the management API resources except /login is protected by JWT auth. Therefore, it is necessary to send the token as a bearer token when invoking the API resources.

curl -X GET "https://localhost:9164/management/inbound-endpoints" -H "accept: application/json" -H "Authorization: Bearer %AccessToken%”

Log out from management API

Invoke the /logout resource to revoke the JWT token you used for invoking the api resource.

curl -X GET "https://localhost:9164/management/logout” -H "accept: application/json" -H "Authorization: Bearer %AccessToken%”

Accessig API resources

The management API has multiple resources to provide information regarding the deployed artifacts as well as the server itself.

GET PROXY SERVICES

• Resource: /proxy-services

  Description: Retrieves a list of all deployed proxy services.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/proxy-services" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
    "count": 1,
    "list": [
      {
        "name": "TestProxy",
        "wsdl1_1": "http://ThinkPad-X1-Carbon-3rd:8290/services/TestProxy?wsdl",
        "wsdl2_0": "http://ThinkPad-X1-Carbon-3rd:8290/services/TestProxy?wsdl2"
      }
    ]
  }

• Resource: /proxy-services?proxyServiceName={proxyName}

  Description: Retrieves information related to a specified proxy.

  Example:

  curl -X GET "https://localhost:9164/management/proxy-services?proxyServiceName=helloProxy" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

GET CARBON APPLICATIONS

• Resource: /applications

  Description: This operation provides you a list of available Applications.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/applications" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
    "count": 1,
    "list": [
      {
        "name": "SampleServicesCompositeApplication",
        "version": "1.0.0"
      }
    ]
  }

• Resource: /applications?carbonAppName={appname}

  Description: Retrieves information related to a specified carbon application.

  Example:

  curl -X GET "https://localhost:9164/management/applications?carbonAppName=HelloCApp" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

GET ENDPOINTS

• Resource: /endpoints

  Description: Retrieves a list of available endpoints.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/endpoints" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "count": 2,
      "list": [
      {
          "name": "FailOver_EP",
          "type": "failover"
      },
      {
          "name": "WSDL_EP",
          "type": "wsdl"
      }
      ]
  }

• Resource: /endpoints?endpointName={endpointname}

  Description: Retrieves information related to a specified endpoint.

GET APIs

• Resource: /apis

  Description: Retrieves a list of available apis.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/apis" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "count": 2,
      "list": [
      {
          "name": "api",
          "url": "http://localhost:8290/test"
      },
      {
          "name": "helloApi",
          "url": "http://localhost:8290/api"
      }
      ]
  }

• Resource: /apis?apiName={api}

  Description: Retrieves information related to a specified api.

GET SEQUENCES

• Resource: /sequences

  Description: Retrieves a list of available sequences.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/sequences" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "count": 3,
      "list": [
      {
          "tracing": "disabled",
          "stats": "disabled",
          "name": "fault"
      },
      {
          "container": "[ Deployed From Artifact Container: helloCompositeApplication ] ",
          "tracing": "disabled",
          "stats": "disabled",
          "name": "sequenceForSampler"
      },
      {
          "tracing": "disabled",
          "stats": "disabled",
          "name": "main"
      }
      ]
  }

• Resource: /sequences?sequenceName={sequence}

  Description: Retrieves information related to a specified sequence.

GET LOCAL ENTRIES

• Resource: /local-entries

  Description: Retrieves a list of available local entries.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/local-entries" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "count": 2,
      "list": [
      {
          "name": "testEntry1",
          "type": "Inline Text"
      },
      {
          "name": "testentry2",
          "type": "Inline XML"
      }
      ]
  }

• Resource: /local-entries?name={entryName}

  Description: Retrieves information related to a specified entry.

GET TASKS

• Resource: /tasks

  Description: Retrieves a list of available tasks.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/tasks" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "count": 1,
      "list": [
      {
          "name": "testTask"
      }
      ]
  }

• Resource: /tasks?taskName={taskName}

  Description: Retrieves information related to a specified task.

GET MESSAGE STORES

• Resource: /message-stores

  Description: Retrieves a list of available message stores.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/message-stores" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "count": 2,
      "list": [
      {
          "size": 0,
          "name": "testMessageStore",
          "type": "in-memory-message-store"
      },
      {
          "size": 0,
          "name": "jdbc_sample_store",
          "type": "jdbc-message-store"
      }
      ]
  }

• Resource: /message-stores?name={messageStore}

  Description: Retrieves information related to a specified message store.

GET MESSAGE PROCESSORS

• Resource: /message-processors

  Description: Retrieves a list of available message processors.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/message-processors" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "count": 2,
      "list": [
      {
          "name": "testMessageProcessor",
          "type": "Scheduled-message-forwarding-processor",
          "status": "active"
      },
      {
          "name": "TestSamplingProcessor",
          "type": "Sampling-processor",
          "status": "active"
      }
      ]
  }

• Resource: /message-processors?name={messageProcessors}

  Description: Retrieves information related to a specified message processor.

POST MESSAGE PROCESSORS

• Resource: /message-processors

  Description: Used to activate or deactivate a specific message processor

  Example:

  curl -X POST \
    https://localhost:9164/management/message-processors \
    -H 'authorization: Bearer Token
    -H 'content-type: application/json' \
    -d '{
      "name": "testMessageProcessor",
      "status": "inactive"
  }'

GET INBOUND ENDPOINTS

• Resource: /inbound-endpoints

  Description: Retrieves a list of available inbound endpoints.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/inbound-endpoints" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "count": 1,
      "list": [
      {
          "protocol": "http",
          "name": "HTTPIEP"
      }
      ]
  }

• Resource: /inbound-endpoints?inboundEndpointName={inboundEndpoint}

  Description: Retrieves information related to a specified inbound endpoint.

GET CONNECTORS

• Resource: /connectors

  Description: Retrieves a list of available connectors.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/connectors" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "count": 2,
      "list": [
      {
          "package": "org.wso2.carbon.connector",
          "name": "fileconnector",
          "description": "wso2 file connector",
          "status": "enabled"
      },
      {
          "package": "org.wso2.carbon.connector",
          "name": "gmail",
          "description": "WSO2 Gmail connector library",
          "status": "enabled"
      }
      ]
  }

GET TEMPLATES

• Resource: /templates

  Description: Retrieves a list of available templates.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/templates" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "sequenceTemplateList": [
      {
          "name": "testSequenceTemplate"
      }
      ],
      "endpointTemplateList": [
      {
          "name": "endpointTemplate"
      }
      ]
  }

• Resource: /templates?type=TYPE

  Description: Retrieves a list of available templates of a given type. Supported template types are as follows. 1. endpoint 2. sequence

  Example:

  Request

  curl -X GET "https://localhost:9164/management/templates?type=sequence" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "count": 1,
      "list": [
      {
          "name": "testSequenceTemplate"
      }
      ]
  }

• Resource: /templates?type={type}&name={template}

  Description: Retrieves information related to a specific template. However this requires the template type to be included in the request as a query parameter in addition to the template name.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/templates?type=sequence&name=testSequenceTemplate" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "Parameters": [],
      "configuration": "<template xmlns=\"http://ws.apache.org/ns/synapse\" name=\"testSequenceTemplate\"><sequence/></template>",
      "name": "testSequenceTemplate"
  }

GET SERVER INFORMATION

• Resource: /server

  Description: Retrieves information related to the micro integrator server instance.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/server" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "productVersion": "1.1.0",
      "repositoryLocation": "/Users/Sachith/IdeaProjects/micro-integrator-public/distribution/target/wso2mi-1.1.0-SNAPSHOT/repository/deployment/client/",
      "osVersion": "10.14",
      "javaVersion": "1.8.0_171",
      "workDirectory": "/Users/Sachith/IdeaProjects/micro-integrator-public/distribution/target/wso2mi-1.1.0-SNAPSHOT/tmp/work",
      "carbonHome": "/Users/Sachith/IdeaProjects/micro-integrator-public/distribution/target/wso2mi-1.1.0-SNAPSHOT",
      "javaVendor": "Oracle Corporation",
      "osName": "Mac OS X",
      "productName": "WSO2 Micro Integrator",
      "javaHome": "/Library/Java/JavaVirtualMachines/jdk1.8.0_171.jdk/Contents/Home/jre"
  }

GET DATA SERVICES

• Resource: /data-services

  Description: Retrieves a list of all data services deployed.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/data-services" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

  Response

  {
      "count": 1,
      "list": [
      {
          "name": "StudentDataService",
          "wsdl1_1": "http://Sachiths-MacBook-Pro.local:8290/services/StudentDataService?wsdl",
          "wsdl2_0": "http://Sachiths-MacBook-Pro.local:8290/services/StudentDataService?wsdl2"
      }
      ]
  }

• Resource: /data-services?dataServiceName={dataservice}

  Description: Retrieves information related to a specific data service.

  Example:

  curl -X GET "https://localhost:9164/management/data-services?dataServiceName=StudentDataService" -H "accept: application/json" -H "Authorization: Bearer TOKEN" -k -i

Logging

Info

The following logging resources are available as a product update from 10^th June, 2020 onwards. See the instructions on getting product updates.

GET LOG LEVEL

• Resource: /logging?loggerName={logger}

  Description: Retrieves information related to a specific logger.

  Example:

  Request

  curl -X GET "https://localhost:9164/management/logging?loggerName=org-apache-coyote" -H "accept: application/json" -H         "Authorization: Bearer Token" -k

  Response

  {
      "loggerName": "org-apache-coyote",
      "level":"WARN",
      "componentName":"org.apache.coyote"
      }

UPDATE ROOT LOG LEVEL

• Resource: /logging

  Description: Updates the log level of root logger.

  Example:

  Request

  curl -X PATCH \
      https://localhost:9164/management/logging \
      -H 'authorization: Bearer Token' \
      -H 'content-type: application/json' \
      -d '{
      "loggerName": "rootLogger",
      "loggingLevel": "WARN"
      }' -k

  Response

  {
      "message": "Successfully updated rootLogger.level to WARN"
      }

UPDATE LOG LEVEL

• Resource: /logging

  Description: Updates the log level of a specific logger.

  Example:

  Request

  curl -X PATCH \
      https://localhost:9164/management/logging \
      -H 'authorization: Bearer Token' \
      -H 'content-type: application/json' \
      -d '{
      "loggerName": "org-apache-hadoop-hive",
      "loggingLevel": "DEBUG"
      }' -k

  Response

  {
      "message": "Successfully updated logger.org-apache-hadoop-hive.level to DEBUG"
      }

Top