Topics
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.
Note:
In WebLogic Server 12.2.1, the dynamic REST resources supported one version,12.2.1.0, and the latest version referred to it. In 12.2.1.1, the dynamic REST resources support two versions:
12.2.1.0 (also referred to as 12.2.1.0.0): this version is now deprecated
12.2.1.1.0: this is the latest version
To summarize the changes in this release:
The 12.2.1.0 REST resources have been deprecated and you should use the 12.2.1.1.0 REST resources instead
The latest version has changed from 12.2.1.0 to 12.2.1.1.0
All new MBean features have been added to the 12.2.1.1.0 and the 12.2.1.0 REST resources, also
Any MBean features that were deprecated in 12.2.1.1.0, will still be available using the 12.2.1.0 REST URLs, but not the 12.2.1.1.0 REST URLs
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.
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).
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 Server (Legacy).
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.
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. |
The following table describes the standard headers that clients should use to send WebLogic Server REST requests.
| Request Header | Description |
|---|---|
|
|
Indicates that the client wants the response to contain JSON. This header is appropriate when invoking the GET, POST, and DELETE methods. Any resources that return other data types are specified in the reference manual and examples. |
|
|
Indicates that the client is sending in a request containing JSON. This header is appropriate for the POST method. Some methods support other content types (for example, when uploading deployments); the reference manual and examples specify when they are supported. |
|
|
Used to protect against Cross-Site Request Forgery (CSRF) attacks via REST. This header is mandatory for the POST and DELETE methods and ignored for the OPTIONS and GET methods. |
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 |
|---|---|---|
|
|
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 |
|
|
Life cycle management (LCM) REST resources. |
n/a |
|
|
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 |
|---|---|---|
|
|
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
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).
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 |
|---|---|---|
|
|
Manages the entire collection. |
|
|
|
Manages a child in the collection. |
|
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.
REST maps the various Java types that the WLS beans use (for example, their properties, operation arguments and return types) to JSON.
Java strings and scalars are mapped to their JSON equivalent.
| Java | JSON | Example (Java to JSON) |
|---|---|---|
|
|
string or null |
"Foo" -> "Foo" null -> null |
|
|
string |
'a' -> "a" |
|
|
number |
7001 -> 7001 |
|
|
number |
1.23 -> 1.23 |
|
|
boolean |
true -> true |
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" ]
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.
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.
The REST resources return these standard HTTP response codes:
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.
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.
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.
A REST method returns 400 (BAD REQUEST) if the request failed because something is wrong in the specified request, for example, invalid argument values.
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).
A REST method returns 403 (FORBIDDEN) if the user is not in the ADMIN, OPERATOR, DEPLOYER or MONITOR role.
A REST method returns 404 (NOT FOUND) if the requested URL does not refer to an existing entity.
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).
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.
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.
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.
Resources use the following formats for returning error messages.
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
}
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"
}
]
}