How to use Weblogic REST API for various management operations - Examples

This post covers how to use weblogic rest api practically using various examples and answers, All your questions like How to enable REST api in weblogic, What can you with RESTful API in weblogic, What are bean trees in weblogic, How to perform various operations like deployment, server creation, What is Tenant Monitoring and how to use it and much more.

Let's get started!.

What is Rest API Management Services in weblogic?

Weblogic 12c has come up with so many features bundled-in.  one of the notable features is RESTful management. This approach lets you to directly access the Weblogic Runtime and configuration data with a simple URL based approach.

No need of WLST (or) JMX codes to do the monitoring (or) configuration changes anymore. You can just hit the URL and get things done.

Note*: The post covers only weblogic 12.2.1. This may not be applicable for legacy weblogic 12.1 version

 

How to Enable RESTful Management Services?

Goto your Domain -> Configuration -> General -> Advanced -> Enable RESTful Management Services and restart the Admin Server.

 

What can you do with RESTful Management API of Weblogic?

After RESTful management Services are enabled you can access the runtime and configuration information about the following resources/objects.

1. Servers
2. Applications
3. DataSources
4. Clusters

and you can perform the day to day operations like, monitoring, Deployment,  Start, Stop including the complex tasks like creating the resources like servers, clusters, data sources etc.

Well, now you do not have to worry about the WLST and python scripts anymore.

All you have to do is just tweak the URL and give the request.

 

Some question might arise. Before moving further, let's clarify them.

 

Is my AdminServer needed All the time?

If you are having questions like. To access the console,  AdminServer is needed so to use this feature do we need to keep my AdminServer up and running all the time

I could say No, But It also depends on your requirement,

RESTFul management is an application installed on all the Admin and managed server (once you enable the feature).  If you want to connect to a single server and get information or perform tasks pertaining to only that instance, you are good to go with that corresponding server's API interface.

For example, In my infrastructure setup,  This will be the URL interfaces.

AdminServer:  http://localhost:17001/management

Managed Server1: http://localhost:17003/management

When I want to get the status of my Managed Server1, I can use the direct managed server interface rather than Admin Server's one.

When I want to perform some domain-level tasks like Creation of services/resources, I will have to pick the Admin Server interface.

 

The scope of Managed Server 

Though you have management REST API installed in every server.  The Basic and fundamental boundaries and privileges of AdminServer and ManagedServer will still prevail.  AdminServer will have access to domainRuntime and domainConfig  bean trees where managed servers can access only their corresponding ServerRuntimeand serverConfigbean trees

 

What are Bean Trees in weblogic?

The WLS beans are derived from Java interfaces. At runtime, WLS constructs internal trees of Java beans that can be used to configure and monitor the system. In prior releases, the bean trees were only exposed via JMX, WLST, and configuration files (for example, config.xml).

In this release, WLS dynamically generates REST resources, incrementally and on-demand at runtime, by using the bean trees and bean info. These REST resources provide an alternative for managing WLS.

If you have worked in WLST in weblogic you might have come across the following bean trees.

1. serverConfig - Configuration information of a specific server  ( All Servers in domains will have this tree including Adminserver)
2. serverRuntime- Runtime information of a specific server   ( All Servers in domains will have this tree including Adminserver)
3. domainConfig - MBean which holds the domain-wide Configuration information ( such as the configuration of all servers and services)
4. domainRuntime - MBean which holds the domain-wide Runtime information ( such as status of all servers and services)
5. edit- Edit the selected bean tree

The tenant-monitoring(A quick way to get things done)

Rather than going through all the hassles of finding the right bean tree and fields to get the required information, weblogic RESTful management API provides a wonderful feature called tenant-monitoring. you can pretty much get your most frequent and important monitoring done using this.

Here are some of the examples to give you some exposure to tenant-monitoring

Note:

To retrieve all Servers

http://localhost:17001/management/tenant-monitoring/servers

 

To retrieve the details about single server

Just add the server name at the end of the previous URL, That's it!

http://localhost:17001/management/tenant-monitoring/servers/mwiserver1

 

To retrieve all data sources

http://localhost:17001/management/tenant-monitoring/datasources

 

To retrieve information for a specific data source

http://localhost:17001/management/tenant-monitoring/datasources/<datasourcename>

 

Retrieve all configured Clusters 

http://localhost:17001/management/tenant-monitoring/clusters

 

To retrieve data for a specific Cluster

http://localhost:17001/management/tenant-monitoring/clusters/<clustername>

 

 

Using The CURL Command Line tool

Note*:  This is not a recommended method as we are passing cleartext password over the --user flag to handle BASIC authentication of RESTful management of weblogic. At the end of this post, You will find a tool named "wlsrestcli" which can be used instead to avoid entering clear text username and password.

mwinventory:RESTAPI_TEST aksarav$ curl  -H X-Requested-By:MyClient -H Accept:application/json -H Content-Type:application/json -X GET http://localhost:17001/m/tenant-monitoring/servers – user weblogic:weblogic1
{"body":{"items":[{"name":"AdminServer","state":"RUNNING","health":"HEALTH_OK"},{"name":"mwiserver1","state":"SHUTDOWN"},{"name":"mwiserver2","state":"SHUTDOWN"},{"name":"mwiserver3","state":"SHUTDOWN"},{"name":"mwiserver4","state":"SHUTDOWN"}]},"messages":[]}

 

Formatting the CURL output

When using CURL to connect to wls restful management API interface, you will get your JSON output as a single liner with no pretty formatting. In order to overcome that, I recommend the following ways

 

json_pp ( Download and use json_pp command in *nix terminal)

$ curl -H X-Requested-By:MyClient \ > -H Accept:application/json \ > -H Content-Type:application/json \ > -X GET http://localhost:17001/management/tenant-monitoring/servers \ > – user weblogic:weblogic1|json_pp { "body": { "items": [ { "health": "HEALTH_OK", "name": "AdminServer", "state": "RUNNING" }, { "name": "mwiserver1", "state": "SHUTDOWN" }, { "name": "mwiserver2", "state": "SHUTDOWN" }, { "name": "mwiserver3", "state": "SHUTDOWN" }, { "name": "mwiserver4", "state": "SHUTDOWN" } ] }, "messages": [] }

python ( 2.6+) ( if you have python 2.6+ version you can use this method)

$ curl -H X-Requested-By:MyClient \ > -H Accept:application/json \ > -H Content-Type:application/json \ > -X GET http://localhost:17001/management/tenant-monitoring/servers \ > – user weblogic:weblogic1|python -m json.tool { "body": { "items": [ { "health": "HEALTH_OK", "name": "AdminServer", "state": "RUNNING" }, { "name": "mwiserver1", "state": "SHUTDOWN" }, { "name": "mwiserver2", "state": "SHUTDOWN" }, { "name": "mwiserver3", "state": "SHUTDOWN" }, { "name": "mwiserver4", "state": "SHUTDOWN" } ] }, "messages": [] }

Using Postman

In the preceding illustration you can see, I am passing the username and password securely in the Authorization section

MBeans and WLS RESTful Management Interface ( A level up )

As we discussed above,  Weblogic Server publishes all their runtime and configuration information in the form of Beans and we have discussed the bean trees and their usage. Now it is time to do something practical. With Weblogic REST Management Interface we can pretty much accomplish everything that we can do with WLST and JMX. Such as

1. Creating Resources like Servers/Clusters/JDBC/JMS etc
2. Monitoring the Resources and Servers
3. Performing a LifeCycle tasks/actions such as Start/Shutdown/Resume/Suspend
4. User Management
5. Application management tasks such as deploy/un-deploy/start/stop
6. Cluster Management tasks  such as start/stop/create/delete/add/remove

The possibilities of the REST Management Interface is very extensive.  All we have to do is to be aware,  What MBean to be approached for the requirement and how to do it with REST Management Interface.

How to frame the API URL

A Basic Syntax of the base Management API  URL is as follows

http://localhost:17001/management/weblogic/<version specifier>

 

here <version> represents the version number of the weblogic, you can use the version number  (or) use latest instead.

you can see the available version by giving GET request to http://localhost:17001/management/weblogic URL

 

The Story of Root Resources

when you access the API with version info (either latest or version number)  you will get the following Results where you can see the Links referring to the Bean Trees, These are called Root Resources

# curl -X GET http://localhost:17001/management/weblogic/latest – user weblogic:weblogic1
{
 "links": [
......
....
 {
 "rel": "edit",
 "href": "http:\/\/localhost:17001\/management\/weblogic\/latest\/edit"
 },
 {
 "rel": "domainConfig",
 "href": "http:\/\/localhost:17001\/management\/weblogic\/latest\/domainConfig"
 },
 {
 "rel": "domainRuntime",
 "href": "http:\/\/localhost:17001\/management\/weblogic\/latest\/domainRuntime"
 },
 {
 "rel": "serverRuntime",
 "href": "http:\/\/localhost:17001\/management\/weblogic\/latest\/serverRuntime"
 },
 {
 "rel": "serverConfig",
 "href": "http:\/\/localhost:17001\/management\/weblogic\/latest\/serverConfig"
 },
 {
 "rel": "currentUser",
 "href": "http:\/\/localhost:17001\/management\/weblogic\/latest\/currentUser"
 }
 ],
 "version": "12.2.1.3.0",
 "isLatest": true,
 "lifecycle": "active"

In the preceding illustration,  I am using Administration Server URL to connect to API interface the result set can be called as Administration Server Root Resources

When you are using Managed Server URL to invoke API interface you will get the following result,  These are managed Server Root Resources

 

# curl -X GET http://localhost:17003/management/weblogic/latest – user weblogic:weblogic1 
{
 "links": [
.....
 {
 "rel": "serverRuntime",
 "href": "http:\/\/localhost:17003\/management\/weblogic\/latest\/serverRuntime"
 },
 {
 "rel": "serverConfig",
 "href": "http:\/\/localhost:17003\/management\/weblogic\/latest\/serverConfig"
 },
 .....

As you might have understood it by now,

• Each Bean Tree represents a link here and if you want to navigate through any of the bean trees, you can use their corresponding links.
• You need to use the AdminServer URL for performing any task at the Domain Scope.
• The Resources displayed will vary respective to the Connection URL ( AdminServer/Managed Server)

 

Filtering the Results

In the below-shown example, I am getting the runtime status of all the servers configured in my weblogic domain

# curl -X GET http://localhost:17001/management/weblogic/latest/domainRuntime/serverLifeCycleRuntimes?fields=name,state\&links=none – user weblogic:weblogic1
{"items": [
    {
        "name": "mwiserver4",
        "state": "SHUTDOWN"
    },
    {
        "name": "mwiserver3",
        "state": "SHUTDOWN"
    },
    {
        "name": "mwiserver2",
        "state": "SHUTDOWN"
    },
    {
        "name": "AdminServer",
        "state": "RUNNING"
    },
    {
        "name": "mwiserver1",
        "state": "SHUTDOWN"
    }
]}

 

 

Note*: We are escaping the ampersand& symbol with slash \ So intentionally we replaced& with\&. In Unix, ampersand sends the command to background

If you have noticed it clearly, We are passing some query string here

fields=name,state and links=none 

these are called result filters

There are four filters supported in wls management service API

1. links
2. excludeLinks
3. fields
4. excludeFields

 

Key Points

• We can limit the fields to be displayed by passing them to the fields parameter
• If you do not want any fields but only links you can use fields=none in the query string
• you can mention the list of links or fields that have to be excluded using excludeLinks (or) excludeFields
• links=none indicates that no canonical, self and various other links should be displayed in the output ( Try to remove the links=none and reissue the request to know the difference)

How to find the Right method(GET/POST/DELETE) for an API Call?

So far in this post, we have been using the GET method in API calls.

Let's suppose that you want to update the port number of the managed server instance in your domain. How would you pass the new port number to the REST Management interface?

Let's suppose that you need to delete some resource or a server/cluster from the weblogic domain. How would you do that?

That's where you need to be aware of which method should be used while invoking certain tasks.

For the first requirement, you need to use POST method, in which you need to pass the new port number as a JSON object in the request body

For the second requirement, you need to use DELETE method.

Do not Panic 🙂

In this reference link, https://docs.oracle.com/middleware/1221/wls/WLRUR/intro.htm#WLRUR186   you can find the complete list of weblogic Restful interface URLs and their supported methods and the weblogic security roles who have privileges to invoke them.

 

WLSREST-CLI Helper tool 

A Python script created to efficiently pass the username and password while making REST API calls using C-URL command. It will collect the username and password before making a request and send it as an Authorization Header so that you do not have to worry about the "Shoulder Surfing" or Sharing the system with other people etc. It will not be saved in history (or) anywhere,  It does not save any data and the credentials you are entering pertains only to a single session.

 

How to use it?

Just download it to any python and curl installed server/box and set proper execute permission and execute it.

All the following examples are prepared with the wlsrestcli tool. It can serve as a better guide on how to use the script right.

 

How to Download it? 

Please click here to download it

 

 

Practical Examples using Various Methods (with Video )

 

Start Editing session

We need to start the editing session before making any configuration changes with the help of edit bean tree, you can relate it to clicking the Lock&Edit button on the console before performing any configuration change in the weblogic console.

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{}" \
-X POST http://localhost:17001/management/weblogic/latest/edit/changeManager/startEdit

RestStartEditing from SaravAK on Vimeo.

Create a new Managed Server 

To create a new Managed Server in the domain, you must start with retrieving the server Create Form from edit bean tree and update the fields and send it back to create link. See the video for more info.

Obtain create Server Form
-------------------------
curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-X GET http://localhost:17001/management/weblogic/latest/edit/serverCreateForm

Fill the form and send to create Server
----------------------------------------
curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
name: mwiServer6,
listenAddress: localhost,
listenPort: 17010
}" \
-X POST http://localhost:17001/management/weblogic/latest/edit/servers

Activate the Changes
--------------------
curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{}" \
-X POST http://localhost:17001/management/weblogic/latest/edit/changeManager/activate

REST-CreateServer from SaravAK on Vimeo.

 

Start and Stop the Server

To Start and Stop the Server using WLS REST API, You must have node manager running as it passes the request to node manager for performing the start (or) stop just like AdminConsole.

start managed server
---------------------
curl -v \
-H Content-Type:application/json \
-H Host:localhost \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-d "{}" \
-X POST http://localhost:17001/management/weblogic/latest/domainRuntime/serverLifeCycleRuntimes/mwiserver1/start

shutdown a managed server
--------------------------
curl -v \
-H Content-Type:application/json \
-H Host:localhost \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-d "{}" \
-X POST http://localhost:17001/management/weblogic/latest/domainRuntime/serverLifeCycleRuntimes/mwiserver1/shutdown

Deployment-Related Tasks (Deploy, Undeploy, Update, Redeploy, Start, Stop)

We have created some sample application named mwiapp.war we are going to deploy it using RESTful Management API interface.

deploy an application
---------------------
curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
  name:       'mwiapp',
  applicationPath : '/apps/oracle-weblogic/applications/mwiapp.war',
  targets:    ['mwiCluster1'],
  plan: '/apps/oracle-weblogic/applications/plan.xml',
  deploymentOptions: {}
}" \
-X POST http://localhost:17001/management/weblogic/latest/domainRuntime/deploymentManager/deploy



Get State
----------
curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
	target: 'mwiCluster1'
}" \
-X POST http://localhost:17001/management/weblogic/latest/domainRuntime/deploymentManager/appDeploymentRuntimes/mwiapp/getState


Redeploy an Application
------------------------
curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
  targets:    ['mwiCluster1'],
  plan: '/apps/oracle-weblogic/applications/plan.xml',
  deploymentOptions: {}
}" \
-X POST http://localhost:17001/management/weblogic/latest/domainRuntime/deploymentManager/appDeploymentRuntimes/mwiapp/redeploy

Start an Application
--------------------
curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
  targets:    ['mwiCluster1'],
  deploymentOptions: {}
}" \
-X POST http://localhost:17001/management/weblogic/latest/domainRuntime/deploymentManager/appDeploymentRuntimes/mwiapp/start



Stop an Application
--------------------

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
  targets:    ['mwiCluster1'],
  deploymentOptions: {}
}" \
-X POST http://localhost:17001/management/weblogic/latest/domainRuntime/deploymentManager/appDeploymentRuntimes/mwiapp/stop


undeploy an Application
------------------------

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
  targets:    ['mwiCluster1'],
  deploymentOptions: {}
}" \
-X POST http://localhost:17001/management/weblogic/latest/domainRuntime/deploymentManager/appDeploymentRuntimes/mwiapp/undeploy


update an Application
----------------------

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
  targets:    ['mwiCluster1'],
  deploymentOptions: {},
  plan: '/apps/oracle-weblogic/applications/plan.xml'
}" \
-X POST http://localhost:17001/management/weblogic/latest/domainRuntime/deploymentManager/appDeploymentRuntimes/mwiapp/update

 

I hope by now, you are well aware of how to trigger a call through CURL by using the right method. I am gonna leave some of the CURL snippets here for your quick usage and access.  – user argument was not added, as I hope you will use wlrestcli.py for your security. If you are ok with using cleartext password. please go ahead and add the args before executing.

 

Get All Deployed Applications Health State

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{ 
 links: [],
 fields: [],
 children: {
 serverRuntimes: {
 links: [], 
 fields: ['name'],
 children: {
 applicationRuntimes: {
 links: [],
 fields: ['name','healthState','OverallHealthState']
 }
 }
 }
 }
}" \
-X POST http://localhost:17001/management/weblogic/latest/domainRuntime/search

Update/Change the managed server listenport 

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
 listenPort: 17008
}" \
-X POST http://localhost:17001/management/weblogic/latest/edit/servers/mwiserver4

List the Debug flags for managed Server

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-X GET http://localhost:17001/management/weblogic/latest/edit/servers/mwiserver4/serverDebug

 

Enable Debug on HTTP Sessions for the managed Server

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
 debugHttpSessions: true,
 debugHttpLogging: true,
 debugHttp: true
}" \
-X POST http://localhost:17001/management/weblogic/latest/edit/servers/mwiserver4/serverDebug

 

 

Enable JDBC/ Database Connection Debug on Managed Server

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
 debugJDBCConn: true,
 debugJDBCSQL: true
}" \
-X POST http://localhost:17001/management/weblogic/latest/edit/servers/mwiserver4/serverDebug

List of server and their Status 

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-X GET http://localhost:17001/management/weblogic/latest/domainRuntime/serverLifeCycleRuntimes?fields=name,state&links=none

Get the list of servers and their Listen Port

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-X GET http://localhost:17001/management/weblogic/latest/domainConfig/servers?fields=name,listenPort&links=no

Get the status of ALL servers in the domain

curl -v \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-X GET http://localhost:17001/management/weblogic/latest/domainRuntime/serverLifeCycleRuntimes?fields=name,state&links=none

 

I hope this post Justifies to the Title "Weblogic 12c RESTful Management Brief Introduction and Examples".

 

 

Cheers
Sarav AK

---

 

 

References:

https://docs.oracle.com/middleware/1221/wls/WLRUR/toc.htm

https://docs.oracle.com/middleware/1221/wls/WLRDR/resources.htm