2 About the WLS RESTful Management Interface

WebLogic RESTful management services provide a comprehensive public interface for configuring, monitoring, deploying and administering WebLogic Server in all supported environments. This chapter describes the RESTful management services supported by WebLogic Server.


Overview of the WLS RESTful Management Interface

In each release of WebLogic Server, the availability of REST resources for WebLogic Server administration has been enhanced and extended. This release 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 partitioned and non-partitioned 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.

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 12.2.1 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

The following sections describe how WLS beans are mapped to the REST interfaces. Some commonalities are:

  • All resource URLs contain version numbers, and support a version named latest. For more information, see "The {version} Specifier in Resource URLs" in the RESTful Management Interface Reference for Oracle WebLogic.

  • All request bodies and response bodies use JSON (media type is application/json).

  • Response bodies have a standard set of properties—items (to return information about collections), links (to return links to related resources), and messages (to return success, warning, and failure messages).

  • All resources return standard HTTP response codes—201 for successful creation, 200 for other successes, 404 for not found, 400 for user input errors, 500 for internal server errors. For more information, see Standard REST Responses.

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 12.2.1 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


Edits the WLS configuration.

Administration Server's edit tree domain bean


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

Administration Server's server runtime tree domain bean


Monitors the Administration Server.

Administration Server's server runtime tree server runtime bean


Views the last activated WLS configuration.

Administration Server's domain runtime tree domain bean


Monitors the entire WLS domain.

Administration Server's domain runtime tree domain runtime bean


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

Each running server's server runtime tree server runtime bean


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

The specified server's server runtime tree server runtime bean


12.2.1 life cycle management (LCM) REST resources.



12.1.3 (legacy) WLS REST resources.


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

Table 2-2 Managed Server Root Resources

URL Description Corresponding Bean Tree


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

Managed Server's server runtime tree domain bean


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"




number 7001 -> 7001




number 1.23 -> 1.23


boolean true -> true


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


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 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.

Standard REST Responses

The 12.2.1 REST resources return these standard HTTP response codes:

200 OK

A REST method returns 200 (OK) if the operation succeeds and does not create a new entity, for example, GET a resource, POST to invoke an operation or modify an entity, DELETE to remove an entity.

201 Created

A REST method returns 201 (CREATED) if the operation successfully created a new entity. It also returns a Location header with a link to the new entity.

202 Accepted

A REST method returns 202 (ACCEPTED) if the operation successfully initiated some asynchronous work. It also returns a Location header with a link to a resource that you can poll to find out the status of the job.

400 Bad Request

A REST method returns 400 (BAD REQUEST) if the request failed because something is wrong in the specified request, for example, invalid argument values.

401 Unauthorized

A REST method returns 401 (UNAUTHORIZED) if the user does not have permission to perform the operation. 401 is also returned if the user supplied incorrect credentials (for example, a bad password).

403 Forbidden

A REST method returns 403 (FORBIDDEN) if the user is not in the ADMIN, OPERATOR, DEPLOYER or MONITOR role.

404 Not Found

A REST method returns 404 (NOT FOUND) if the requested URL does not refer to an existing entity.

405 Method Not Allowed

A REST method returns 405 (METHOD NOT ALLOWED) if the resource exists but does not support the HTTP method, for example, if the user tries to create a server by using a resource in the domain configuration tree (only the edit tree allows configuration editing).

406 Not Acceptable

The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request. For example, the client's Accept header asks for XML but the resource can only return JSON.

500 Internal Server Error

A REST method returns 500 (INTERNAL SERVER ERROR) if an error occurred that is not caused by something wrong in the request. Since the REST layer generally treats exceptions thrown by the MBeans as BAD REQUEST, 500 is generally used for reporting unexpected exceptions that occur in the REST layer. These responses do not include the text of the error or a stack trace, however, generally they are logged in the server log.

503 Service Unavailable

The server is currently unable to handle the request due to temporary overloading or maintenance of the server. The WLS REST web application is not currently running.

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"