2 About the WLS RESTful Management Interface

Learn about the Oracle 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 Oracle WebLogic Server. This chapter includes the following topics:

• Introduction to the WLS RESTful Management Interface
  The Oracle WebLogic Server RESTful management interface provides comprehensive support for Oracle WebLogic Server administration through the dynamic generation of REST resources based on WLS MBeans and descriptor interfaces.
• Mapping the WLS Beans to REST
  Learn how the WLS beans are mapped to the REST interfaces.
• Returning Error Messages
  Resources use different formats for returning error messages.

Introduction to the WLS RESTful Management Interface

The Oracle WebLogic Server RESTful management interface provides comprehensive support for Oracle 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 Information Roadmap.

Note:

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

• 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. However, they will not available for the 14.1.1.0.0 REST URLs.

• Generated REST API for WLS Bean Trees
  
• WLS Bean Tree Overview
  

Generated REST API for WLS Bean Trees

The 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 exposed only through JMX, WLST, and configuration files (for example, config.xml).

In this release, WLS dynamically generates the 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 the 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, and so on).

WLS provides the following bean trees:

• Edit access: Available only 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: Available only 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.

The Oracle 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 the WLS beans are mapped to the REST interfaces.

• General REST Patterns
  
• About the Root Resources
  
• Naming Conventions
  
• Mapping the REST URLs
  
• JSON Mappings
  

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 does not.
	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.	The Administration Server's domain runtime tree domain bean.
management/weblogic/<version>/domainRuntime	Monitors the entire WLS domain.	The 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 the 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, the URL to view the Administration Server's server runtime:

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

The URL to view a Managed Server's server runtime:

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

Naming Conventions

The WLS bean property names are mapped to names in the REST URLs and JSON object properties. The 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). For information about these beans, see 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
  
• Arrays
  
• Identities
  
• WLS Bean References
  
• java.util.Properties
  
• Encrypted Properties
  

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, such as 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 different 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"
    }
  ]
}