2 About the WLS RESTful Management Interface

Learn about the WebLogic Server RESTful management interface, and how the WLS MBeans are mapped to the REST interfaces.

This chapter describes the RESTful management services supported by WebLogic Server.

Introduction to the WLS RESTful Management Interface

The WebLogic Server RESTful management interface provides comprehensive support for WebLogic Server administration through the dynamic generation of REST resources based on WLS MBeans and descriptor interfaces. There are resources to support the configuration and monitoring of domain environments, life cycle management (LCM) resources, and legacy resources from 12.1.3.

For a guide to the WLS REST reference documentation, see the Information Roadmap.

Note:

In WebLogic Server 14.1.1.0.0:

  • All prior versions are now deprecated: 12.2.1.0.0, 12.2.1.1.0, 12.2.1.2.0, 12.2.1.3.0 and 12.2.1.4.0

  • 14.1.1.0.0: this is the latest version

To summarize the changes in this release:

  • All prior versions have been deprecated and you should use the 14.1.1.0.0 REST resources instead

  • The latest version has changed from 12.2.1.4.0 to 14.1.1.0.0

  • All new MBean features added in 14.1.1.0.0 will show up in 12.2.1.1.0, 12.2.1.2.0, 12.2.1.3.0 and 12.2.1.4.0, also

  • Any MBean features that were deprecated in 14.1.1.0.0, will still be available using the 12.2.1.1.0, 12.2.1.2.0, 12.2.1.3.0 and 12.2.1.4.0 REST URLs, but not the 14.1.1.0.0 REST URLs

Generated REST API for WLS Bean Trees

WLS beans are used extensively by WLS components to manage configuration settings and to monitor and manage running servers.

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 infos. These REST resources provide an alternative for managing WLS.

WLS Bean Tree Overview

The following sections provide background information about WLS beans which provide the foundation for the REST interfaces.

There are two main bean types:

  • Configuration—used to configure WLS.

  • Runtime—used to monitor WLS and for some operations, control WLS (for example, starting and stopping servers, shrinking data source connection pools).

WLS provides the following bean trees:

  • Edit access—only available on the Administration Server, used to modify the configuration (for example, config.xml and system resource files).

  • Runtime access—available on every server, used to view that server's configuration and to access its monitoring data.

  • Domain access—only available on the Administration Server, contains copies of the runtime beans of all of the running servers, provides a single point of access for monitoring, is also used to view the most current configuration that has been persisted.

For more information about WLS MBeans, see Understanding WebLogic Server MBeans in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.

WebLogic Scripting Tool (WLST) presents the bean trees as follows:

  • edit—matches the underlying edit access bean tree.

  • domainConfig—the configuration MBean half of the domain access bean tree (such as, the last persisted configuration).

  • domainRuntime—the runtime MBean half of the domain access bean tree (such as, for monitoring all servers).

  • serverConfig—the configuration MBean half of the runtime access bean tree (such as, the configuration the server is using).

  • serverRuntime—the runtime MBean half of the runtime access bean tree (such as, for monitoring a specific server).

The REST resources parallel the MBean trees presentation in WLST: edit, domainConfig, domainRuntime, serverConfig, and serverRuntime.

Within the WLS bean trees, there are several types of parent/child (containment) relationships:

  • Writable collections—for example, a domain bean has a collection of server beans.

  • Mandatory singletons—for example, a server bean always has an SSL bean which is automatically created and cannot be deleted.

  • Optional singletons—for example, an overload protection bean can optionally have a server failure trigger bean.

Beans can include properties (generally scalars, strings, and arrays), references to other beans, and operations (for example, to start a server).

With regard to contained collections:

  • Each child has a unique identity within the collection (for example, each network channel has a name that's unique within its server).

  • Most collections are homogeneous (for example, a domain's applications) though a few are heterogeneous (for example, a security realm's authentication providers).

Mapping the WLS Beans to REST

Learn how WLS beans are mapped to the REST interfaces.

General REST Patterns

Almost all of the WLS beans (a homogeneous collection of children, a mandatory singleton child, and an optional homogenous singleton child) use the following REST patterns:

WLS Beans/REST Resource REST Method Description

Collections: collection resource

GET

Returns the collection.

POST

Creates a new item in the collection.

Collections: create form resource

GET

Returns a pre-populated entity.

Collections: child resource

GET

Returns an item in the collection.

POST

Updates an item in the collection.

DELETE

Removes an item from the collection.

Singletons: singleton resource

GET

Returns the singleton.

POST

Updates the singleton if it exists; creates it if it doesn't.

DELETE

Removes the singleton.

Operations: action resource

POST

Invokes the operation.

About the Root Resources

The Administration Server and each running Managed Server hosts a REST web application that runs on each server's administrative port. The context root for each is management. The root REST resources mimic the bean trees in WLST.

Table 2-1 describes the root resources on the Administration Server and lists the corresponding bean tree.

Table 2-1 Administration Server Root Resources

URL Description Corresponding Bean Tree

management/weblogic/<version>/edit

Edits the WLS configuration.

Administration Server's edit tree domain bean

management/weblogic/<version>/serverConfig

Views the WLS configuration that the Administration Server is currently running against.

Administration Server's server runtime tree domain bean

management/weblogic/<version>/serverRuntime

Monitors the Administration Server.

Administration Server's server runtime tree server runtime bean

management/weblogic/<version>/domainConfig

Views the last activated WLS configuration.

Administration Server's domain runtime tree domain bean

management/weblogic/<version>/domainRuntime

Monitors the entire WLS domain.

Administration Server's domain runtime tree domain runtime bean

management/weblogic/<version>/domainRuntime/serverRuntimes

Monitors all the running servers in the WLS domain via the Administration Server.

Each running server's server runtime tree server runtime bean

management/weblogic/<version>/domainRuntime/serverRuntimes/<serverName>

Monitors a specific running server in the WLS domain via the Administration Server.

The specified server's server runtime tree server runtime bean

management/lifecycle

Life cycle management (LCM) REST resources.

n/a

management/wls

12.1.3 (legacy) WLS REST resources.

n/a

Table 2-2 describes the root resources on Managed Servers.

Table 2-2 Managed Server Root Resources

URL Description Corresponding Bean Tree

management/weblogic/<version>/serverConfig

Views the WLS configuration that a Managed Server is currently running against.

Managed Server's server runtime tree domain bean

management/weblogic/<version>/serverRuntime

Monitors that Managed Server.

Managed Server's server runtime tree server runtime bean

The URLs on Managed Servers are exactly like the ones on the Administration Server, except that the host and port are different.

For example, to view the Administration Server's server runtime:

curl ... -X GET http://adminHost:7001/management/weblogic/latest/serverRuntime

To view a Managed Server's server runtime:

curl ... -X GET http://managed1Host:7002/management/weblogic/latest/serverRuntime

Naming Conventions

WLS bean property names are mapped to names in the REST URLs and JSON object properties. WLS property names usually start with an upper case letter (for example, Domain, JDBCDataSource, ServerRuntime) whereas the REST naming conventions use camel case, lower then upper case letters (for example, domain, JDBCDataSource, serverRuntime).

Mapping the REST URLs

Each WLS bean is mapped to a separate REST resource. Contained collections and operations are also mapped to separate resources. All WLS beans are either root resources (for example, the domain), contained collection children (for example, servers) or contained singleton children (for example, a server's SSL configuration).

The URLs for the root resources are listed in Table 2-1 and Table 2-2.

Each contained collection bean property maps to a URL for the entire collection as well as a URL for each child. For example:

URL Description Example

<parent>/<collectionPropertyName>

Manages the entire collection.

.../edit/servers

<parent>/<collectionPropertyName>/<childName>

Manages a child in the collection.

.../edit/servers/Server-0

Similarly, each contained singleton bean property maps to its own URL. For example, a server's SSL bean maps to .../edit/servers/<serverName>/SSL.

If a contained bean property is creatable (for example, you can add a new server to the domain's servers collection, or you can create an RDBMSSecurityStore for the domain), then create form resources are also provided which return a template JSON object with default values to help you create the new resource. The general procedure is that you GET the create form, fill in the values, then POST it back to create the new resource. If any fields are not filled in, they retain their current values. The URLs of the create form resources are <parent>/<singlularCollectionPropertyName>CreateForm, for example:

  • .../edit/serverCreateForm

  • .../edit/securityConfiguration/realms/myrealm/RDBMSSecurityStoreCreateForm

Each bean operation maps to its own URL. For example, .../domainRuntime/serverRuntimes/<serverName>/shutdown is used to shut down a specific server.

Most of the WLS bean operations are used to create, delete, list, and find contained beans. These operations are handled separately in REST (versus exposed as REST operation URLs). They are described in Using the WLS RESTful Management Interface.

JSON Mappings

REST maps the various Java types that the WLS beans use (for example, their properties, operation arguments and return types) to JSON.

Strings and Scalars

Java strings and scalars are mapped to their JSON equivalent.

Java JSON Example (Java to JSON)

java.lang.String

string or null

"Foo" -> "Foo"

null -> null

char, java.lang.Character

string

'a' -> "a"

int

java.lang.Integer

long

java.lang.Long

number

7001 -> 7001

float

java.lang.Float

double

java.lang.Double

number

1.23 -> 1.23

boolean

java.lang.Boolean

boolean

true -> true

Arrays

Non-null Java arrays are mapped to JSON arrays. Null Java arrays are mapped to a JSON null.

Identities

Each WLS bean is uniquely identified within its bean tree by the trailing part of its URL, after the version specifier. For example, edit/machines/Machine-0.

This identity is mapped to a JSON string array, with one string for each path segment past the root resource of the tree, for example:

[ "machines", "Machine-0" ]
WLS Bean References

Some WLS bean properties contain references to other WLS beans (versus a containment relationship). The same is true for operation arguments and return types. For example, a Server bean has a reference to a Machine bean, and a Deployment bean has a reference to an array of Target beans.

Singleton references (for example, a server's machine) map to a property whose value is the identity of the referenced bean, as well as a link, for example:

{
  machine: [ "domain", "machines", "Machine-0" ],
  links: [
    { rel: "machine", href: "http://localhost:7001/management/latest/weblogic/edit/machines/Machine-0" }
  ]
}

Collections of references (for example, a server's candidate machines) map to an array property where each element is an object containing the referenced bean's identity as well as a link to the bean, for example:

{
  candidateMachines: [
    {
      identity: [ "machines", "Machine-0" ],
      links [ { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/machines/Machine-0"
    },
    {
      identity: [ "machines", "Machine-1" ],
      links [ { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/machines/Machine-1"
    }
  ]
}

A null reference or null reference collection is mapped to a JSON null.

java.util.Properties

java.util.Properties holds lists of properties, for example, a CommonLogMBean LoggerSeverityProperties property. It is mapped to a JSON object, with a matching string property for each property in the set of properties, for example:

{
  "property1": "value1",
  "property2": "value2"
}

Null java.util.Properties are mapped to a JSON null.

Encrypted Properties

Some WLS bean string properties are encrypted because they hold sensitive data like passwords. While clients must be able to set passwords (this is done by passing them in as cleartext strings), other users are not allowed to view them but they might want to know whether the password has a value (versus null, is not set).

The mapping is different for inbound versus outbound encrypted properties.

For outbound encrypted properties, if the password is null, it is mapped to a JSON null. If not, then it is mapped to the JSON string @Oracle_Confidential_Property_Set_V1.1#.

For inbound encrypted properties, you would typically perform a GET to get the current value of a resource, set the values for the properties that should be changed, leaving the others with their current values, then POST the new value back. Therefore, if the value in the POST is @Oracle_Confidential_Property_Set_V1.1#, then the property is not changed (it retains the old property value). Otherwise, the value is changed to the cleartext string value in the POST.

Returning Error Messages

Resources use the following formats for returning error messages.

Error Messages with One Error String

If a resource returns one error string, it uses this format:

HTTP/1.1 400 Bad Request
{
  type: "http://oracle/TBD/WlsRestMessageSchema",
  title: "FAILURE",
  detail: "Bean already exists: \"weblogic.management.configuration.ServerMBeanImpl@31fa1656([mydomain]/Servers[Server-1])\"",
  status: 400
}
Error Messages with More Than One Error String

If a resource returns more than one error string, it uses this format:

HTTP/1.1 400 Bad Request
{
  type: "http://oracle/TBD/WlsRestMessagesSchema",
  title: "ERRORS",
  status: 400,
  wls:errorsDetails: [
    {
      type: "http://oracle/TBD/WlsRestMessageSchema",
      title: "FAILURE",
      detail: "no-such-protocol is not a legal value for DefaultProtocol.\
      The value must be one of the following: [t3, t3s, http, https, iiop, iiops]",
      o:errorPat: "defaultProtocol"
    },
    {
      type: "http://oracle/TBD/WlsRestMessageSchema",
      title: "FAILURE",
      detail: "Type mismatch. Cannot convert abc to int",
      o:errorPath: "listenPort"
    }
  ]
}