3 Using the WLS RESTful Management Interface

Learn how to use the RESTful management services supported by WebLogic Server. For example scripts that show how to use the WLS REST APIs to perform common domain management and monitoring tasks, see Domain Level REST API Examples.

This chapter includes the following sections:

Accessing REST Resources

Each REST resource method documents which user roles can access it: Admin, Deployer, Operator, Monitor.

In general:

  • You must be in the Admin, Deployer, Operator, or Monitor role to read resources (use the GET method).

  • You must be in the Admin role to write resources (use the POST and DELETE methods) or to invoke operations (using POST).

  • However, with certain resources, a Deployer can deploy and undeploy applications and libraries, and an Operator can start a server.

For a domain user (for example, a user defined in the domain's default security realm), the URL to access REST resources starts with http://host:port/management.

Viewing WLS Beans

To view a WLS bean, invoke the HTTP GET method on its corresponding REST URL.

For example, to get the configuration for the server, Server-0:

GET http://localhost:7001/management/weblogic/latest/edit/servers/Server-0

GET returns a standard WLS REST response body. It returns a JSON object containing the bean's properties and a links property, a JSON array containing links to related resources.

About WLS Bean Properties

The returned JSON object contains the WLS bean's properties (for example, typical properties and references, but not children), using the standard Java to JSON mappings (see JSON Mappings). It also includes an identity property that specifies the bean's identity. For example:

{
  identity: [ "domain", "servers", "Server-0" ],
  name: 'Server-0',
  listenPort: 7001,
  machine: { identity: [ "domain", "machines", "Machine-0" ] }
}

Self and Canonical Links

All resources include a self and a canonical top level link that refer to the resource. For example, a server contains self and canonical links that refer to the specified server:

{
  links: [
    { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" }
    { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" }
   ]
}

The cross-references of these links refer to that REST resource also, therefore, include the name of the tree in which the resource is a child, for example, edit, domainRuntime, serverConfiguration, and such.

Parent Links

All resources, except for root resources, include a top level link to their parent resource. The link's rel property is set to parent.

Collection children return links to the collection resource, for example, a server returns a link to the server's collection resource:

{
  links: [
    { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit/servers" }
   ]
}

Similarly, singleton children return links to their parent resource, for example, an SSL bean returns a link to the server bean:

{
  links: [
    { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" }
  ]
}

Self Create Form Links

If a bean is a creatable, optional singleton (for example, a realm's RDBMSSecurityStore), and the bean currently does not exist, then a link to its corresponding create form resource is also returned. The link's rel property is set to create. For example, calling GET on a security realm's adjudicator also returns:

{
  links: [
     {
       rel: "create",
       href: "http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myrealm/adjudicatorCreateForm"
     }
  ]
}

Child Bean Links

Since a WLS bean's containment properties (for example, children) are mapped to separate REST resources, they are returned as top level links in the JSON response body.

Each link's rel property is mapped to the bean property's name. For example, calling GET on Server-0 returns:

{
  links: [
    // mandatory singleton child:
    {
      rel: "SSL",
      href: "http://localhost:7001/management/weblogic/latest/servers/Server-0/SSL"
    },
    // writable collection of children:
    {
      rel: "networkAccessPoints",
      href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0/networkAccessPoints"
    }
  ]
}

Child Create Form Links

Links to create form resources are returned for creatable containment properties (singletons and collections). The link's rel property is set to <singularPropertyName>CreateForm. For example, calling GET on Server-0 also returns:

{
  links: [
     {
       rel: "networkAccessPointCreateForm",
       href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0/networkAccessPointCreateForm"
     }
  ]
}

Singleton Bean Reference Links

WLS beans return top level links for each non-null singleton reference. The link's rel property is set to the name of the reference property. For example, if Server-0 refers to Machine-0:

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

If Server-0 has no machine reference:

{
  machine: null
}

Bean Reference Collection Links

WLS beans return nested links for each reference in a reference collection. The link's rel property is set to self.

For example, if Application-0 refers to the targets Server-0 and Cluster-0:

{
  targets: [
    {
      identity: ["clusters", "Cluster-0" ],
      links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/clusters/Cluster-0" } ]
    },
    {
      identity: ["servers", "Server-0" ],
      links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" } ]
    }
}

Operation Links

Resources also return top level links to their operation resources. The links' rel properties are set to action and the links' titles are set to the name of the operation. For example, a ServerRuntimeMBean returns:

{
  links: [
    {
      rel: "action",
      title: "suspend",
      href: "http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/suspend"
    },
    {
      rel: "action",
      title: "resume",
      href: "http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/resume"
    },
    {
      rel: "action",
      title: "shutdown",
      href: "http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/shutdown"
    }
  ]
}

Viewing Collections of Contains Beans

To view a collection of WLS beans, invoke the HTTP GET method on its corresponding REST URL.

For example, to get the configuration of all the servers:

GET http://localhost:7001/management/weblogic/latest/edit/servers

GET returns a standard WLS REST response body. items contains the children's properties. Each item has embedded self and canonical links to that child's resource.

Only the immediate children are returned. For example, if you get the servers collection, each server's properties will be returned, but the server's children (such as SSL) are not returned.

About Collection items

The resource returns a JSON object for each child in the collection. These objects contain the same data as the items returned from calling GET on the children's resources. For example, getting the domain bean's servers collection returns:

{
  items: [
    { name: "Server-1", listenPort: 7001, ... },
    { name: "Server-2", listenPort: 7003, ... }
  ]
}

About Collection Links

A collection resource returns the following links:

  • self and canonical links to itself.

  • A link to its parent.

  • A link to its corresponding create form resource if the collection is writable.

  • Nested self and canonical links to each of its children.

For example, getting the domain bean's servers collection returns:

{
  items: [
    {
      name: "Server-1",
      listenPort: 7001,
      links: [
        { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" }
        { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" }
      ]
    },
    {
      name: "Server-2",
      listenPort: 7005,
      links: [
        { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" }
        { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" }
      ]
    }
  ]
  links: [
    { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers" }
    { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers" }
    { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit" }
    { rel: "create-form", href: "http://localhost:7001/management/weblogic/latest/edit/serverCreateForm" }
  ]
}

Retrieving Create Forms

To retrieve a create form for creating a new resource, invoke the HTTP GET method on its corresponding create form REST URL.

For example, to retrieve a create form for creating a new server:

GET http://localhost:7001/management/weblogic/latest/edit/serverCreateForm

GET returns a standard WLS REST response body. It returns a JSON object containing the create form's properties and a links property which is a JSON array containing links to related resources.

About Create Form Properties

The returned JSON object contains a property for each writable property (normal properties and references) that may be specified when creating a new resource of that type. The property's value will either be the default value from the type's bean info (if available), or the default value for the property's type (for example, 0 for an int). The values for reference properties are always null. For example, getting the domain's serverCreateForm returns:

{
  name: null, // identity - unique names are not generated
  idleConnectionTimeout: 65, // from the default value in the bean info
  replicationGroup: null, // default value for a String since the bean info does not provide a default value
  machine: null, // singleton reference
  candidateMachines: null, // reference collection
  ...
}

About Create Form Links

A create form returns the following links:

  • self and canonical links to itself.

  • A link to its parent.

  • A create link to the corresponding resource that can be used to create a resource of this type.

For example, getting the domain bean's serverCreateForm returns:

{
  links: [
    { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit" },
    { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/serverCreateForm" },
    { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/serverCreateForm" },
    { rel: "create", href: "http://localhost:7001/management/weblogic/latest/edit/servers" }
  ]
}

Filtering Results

Bean, collection, and create form resource GET methods support these query parameters to let you omit properties and links from the response.

Parameter Name Description

fields

Only return these properties.

excludeFields

Return all properties except for these properties.

links

Only return links with these rel names.

excludeLinks

Return all links except for the ones with these rel names.

fields and excludeFields are mutually exclusive, as are links and excludeLinks. All the values are comma-separated lists of names.

For example, to only retrieve a server's self and parent links, and name and listenPort properties:

curl ... -X GET http://localhost:7001/management/weblogic/latest/edit/servers/myserver\
  ?fields=name,listenPort\&links=self,parent
{
  links: [
    { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit/servers" },
    { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/myserver" }
  ],
  name: "myserver",
  listenPort: 7001
}

Modifying the WLS Configuration

You can create, modify and delete beans in the edit tree only (.../management/weblogic/<version>/edit/...). The other bean trees are read-only.

All WLS bean edits must be performed within a configuration transaction:

  • If you already have started a transaction, the REST changes will be made in the same transaction. You will still be responsible for committing or rolling back the transaction.

  • If you have not started a transaction, the REST resource will begin a transaction on your behalf, try to make the changes, and either commit or roll back the transaction depending on whether the changes could be made (auto-transactions).

  • If someone else already has started a transaction, the REST resource will return an error (instead of modifying the configuration).

Sometimes a configuration transaction cannot be committed unless complementary changes to multiple beans are made in the same transaction. In these cases, you need to begin and end the transaction explicitly versus relying on auto-transactions.

Also, when the client manages the transaction, each REST call saves the changes (but does not activate them). There is some MBean validation that occurs during the save operation which might cause it to fail. For example, when you create a JDBC system resource, the changes cannot be saved until after its child JDBC resource name is set. For cases like this, use the saveChanges=false query parameter.

See the changeManager resources in RESTful Edit Reference for Oracle WebLogic Server.

Modifying WLS Configuration Beans

To modify a WLS bean, construct a JSON object containing the values you want to change then invoke the HTTP POST method on its corresponding REST URL, passing in that JSON object as the request body.

For example, to change a server's listen port and administration port:

curl ... -d "{
  listenPort: 7007,
  administrationPort: 9007
}" -X POST http://localhost:7001/management/weblogic/latest/edit/servers/Server-0

This is similar to an HTTP PATCH operation where you only modify part of the bean, versus needing to pass in all of the bean's properties every time.

About the JSON Object Request Body

You construct a JSON object containing the values you want to change. Some WLS bean properties are read-only (for example, a server's name). Read-only properties are ignored.

You don't have to pass in all of the bean's properties. Any properties not passed in will retain their current values. As was described in Encrypted Properties, GET returns the value @Oracle_Confidential_Property_Set_V1.1# for an encrypted string property that has a non-null value. If you POST back this value, then the property will retain its current value. If you want to change the encrypted property's value, then set the value to the cleartext string that you want it to be, for example:

{ defaultIIOPPassword: "admin123" }

To change a reference, pass in its identity. The same is true for reference collections. This replaces the reference collection versus adding references to the collection. For example, to set a server's machine to Machine-0 and candidate Machines to Machine-0 and Machine-1:

{
  machine: [ 'machines', 'Machine-0' ] },
  candidateMachines: [
     { identity: [ 'machines', 'Machine-0' ] },
     { identity: [ 'machines', 'Machine-1' ] }
  ]
}

Also, use null to remove references. For example, to remove a server's machine and candidate machines' references:

{
  machine: null,
  candidateMachines: null
}

If you pass in a mixture of valid and invalid values, the valid ones are written and errors are returned for the invalid ones, and overall, the REST method returns an OK status code. For example:

curl ... -d "{
  listenPort: 7007,
  administrationPort: 'foo'
}" -X POST http://localhost:7001/management/weblogic/latest/edit/servers/Server-0
HTTP/1.1 200 OK
{
  messages: [
    {
      severity: "FAILURE",
      field: "administrationPort",
      message: "Something about the value needs to be an integer"
    }
  ]
}

In this example, the listen port is modified and the administration port is not. The method returned an OK status code.

Using Multiple Edit Sessions

In a previous release, WebLogic Server introduced multiple edit sessions, named concurrent edit sessions, which allows more than one administrator to make configuration changes at the same time. These edit sessions are domain scoped. Each scope has a default edit session. Edit session names are unique within a scope, but not across scopes.

For all the REST resources in the edit tree, you must specify which edit session to use—the name of the scope and the name of the edit session within that scope.

The edit session scope name is derived from the URL. When you use a domain-scoped REST URL, then REST uses the domain level scope. Within that scope, REST must know which edit session to use. You can either specify a header which states exactly which edit session to use, or you can let REST use defaulting rules to pick one.

Client Specified Edit Session

You can select the edit session by including a weblogic.edit.session header in the request. The header's value is used as the edit session name. For example:

curl ... -H weblogic.edit.session=MySession ...

Each edit session scope has a default edit session named default. To explicitly select the scope's default edit session:

curl ... -H weblogic.edit.session=default ...

The Default Edit Session

If you did not include the weblogic.edit.session header, the REST resources use the following rules to select an edit session:

  • If you currently have one edit session locked in the scope, REST will use it.

  • Or, if you have created one edit session in the scope, REST will use it.

  • Otherwise, REST will use the scope's default edit session.

Creating WLS Configuration Beans

You create a new WLS configuration bean by calling POST with a JSON structure containing the new bean's properties.

To make this easier, you can use the corresponding create form resource to retrieve a template JSON structure that is populated with default values for the various writeable properties.

URLs For Creating WLS Configuration Beans

To create a collection child, call POST on the collection's URL, for example, http://localhost:7001/management/weblogic/latest/edit/servers.

To create an optional singleton child, call POST on the proposed child's URL, for example, http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myRealm/adjudicator.

To retrieve a create form, call GET on the corresponding create form resource, for example:

http://localhost:7001/management/weblogic/latest/edit/serverCreateForm

And

http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myRealm/adjudicatorCreateForm

Getting a JSON Template

The underlying WLS beans have default values for many properties. You typically want to display these default values and perhaps, customize them, then use them to create a new WLS bean. You can get these default values by calling GET on the corresponding create form resource. For example:

curl ... -X GET http://localhost:7001/management/weblogic/latest/edit/serverCreateForm
HTTP/1.1 200 OK
{
    listenPort: 7001,
    ...
  }
}

Creating the Bean

To create the WLS configuration bean, call POST on a JSON object containing the new bean's properties.

The JSON object does not need to include all the possible properties. Unspecified properties are set to their default values. All collection children need to be assigned a unique identity within their collection, for example, a server needs a unique name. Therefore, the identity property is not optional.

The response contains a location header containing the resource's URL. For example:

curl ... -d "{
  name: "Server-1",
  defaultProtocol: "t3s"
}" -X POST http://localhost:7001/management/weblogic/latest/edit/servers
HTTP/1.1 201 Created
Location: http://localhost:7001/management/weblogic/latest/edit/servers/Server-1
curl -X GET http://localhost:7001/management/weblogic/latest/edit/servers/id/Server-1
HTTP/1.1 200 OK
{
  item: {
    identity: [ "domain", "servers", "Server-1" ],
    name: "Server-1",
    defaultProtocol: "t3s", // specified by the caller
    listenAddress: 7001     // not specified by the caller, therefore set to its default value
  }
}

If a bean with that name already exists, the resource returns a BAD_REQUEST status code along with a failure message. For example:

curl ... -d "{
  name: "Server-1"
}" -X POST http://localhost:7001/management/weblogic/latest/edit/servers
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
}

Similar to updating a WLS configuration bean, you can pass in a mixture of valid and invalid values. Read-only properties and properties that the bean does not support are ignored. If there is an exception setting a property, the resource adds a failure message to the response. After processing all of the properties, if there were any errors, the resource attempts to delete the new bean and returns a BAD_REQUEST status code.

Example 3-1 Mixture of valid and invalid properties

curl ... -d "{
  name: "Server-1",
  listenPort: abc,
  defaultProtocol: "no-such-protocol",
  adminstrationProtocol: "iiop"
}" -X POST http://localhost:7001/management/weblogic/latest/edit/servers
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"
    }
  ]
}

Example 3-2 All valid properties

curl ... -d "{
  name: "Server-1",
  listenPort: 7003,
  defaultProtocol: "https",
  adminstrationProtocol: "iiop"
}" -X POST http://localhost:7001/management/weblogic/latest/edit/servers
HTTP/1.1 201 Created
Location: http://localhost:7001/management/weblogic/latest/edit/servers/Server-1

Deleting WLS Configuration Beans

To delete a WLS bean (both collection children and optional singleton children), invoke the HTTP DELETE operation on its corresponding REST URL. Any references to that bean will be removed also. For example, to delete a server:

curl ... -X DELETE http://localhost:7001/management/weblogic/latest/edit/servers/Server-0

Managing Whether a Property Is Set

An MBean property can either be set or unset. If it is set, its value is persisted (for example, to config.xml) and locked in. If it is unset, then a default value is used. The value can either be the default value for the property's type, a hard coded default value, or a computed default value that runs some custom Java code.

By default, when you call GET on a resource, it returns the property's current value. When you set the value of a String property to null or an empty string, it unsets the property (returns it to its default value).

REST lets you determine whether a property has been set, and explicitly set or unset a property.

If you set the expandedValues query parameter to true when getting a resource, each value is returned as a JSON object with a set Boolean property and a value property that holds the current value. For example, getting a server returns:

curl ... -X GET \
  http://localhost:7001/management/weblogic/latest/edit/servers/myserver?&expandedValues=true
{
  listenPortEnabled: { set: false, value: true }, // currently not set
  name: { set: true, value: "myserver" }, // currently set
  listenPort: { set: true, value: 7003 } // currently set
}

Similarly, you can use the expandedValues query parameter to explicitly set or unset values. For example, to unset the listen port and set the listen address to an empty string:

curl ... -d "{
  listenPort: { set: false }, // value will be ignored if specified
  listenAddress: { set: true, value: "" }
}" -X POST http://localhost:7001/management/weblogic/latest/edit/servers/myserver?expandedValues=true

Invoking Operations

Each WLS bean operation maps to its own REST URL. In the case of overloaded operations (for example, shutdown() versus shutdown(int, boolean)), all the overloaded operations map to the same URL and the resource looks at the incoming arguments to determine which operation to invoke.

If the operation requires input arguments, they are specified by passing in a JSON object request body with a property for each argument. The name of the property matches the name of the argument.

If the operation does not take input arguments, you must pass in a JSON object with no properties.

Similarly, if the operation returns a value, then it is returned in a standard REST response body's JSON object return property. If the operation is void, the response body does not include an return property.

If the underlying MBean operation throws an exception, the REST method returns a BAD REQUEST (404) response containing the exception's text.

Example 3-3 void operation with no arguments : void shutdown()

curl ... -d "{}" \
-X POST http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/shutdown
{
  // response does not include a 'return' property since it's a void operation
}

Example 3-4 void operation with multiple arguments : void shutdown(int timeout, boolean ignoreSessions)

curl ... -d "{ timeout: 500, ignoreSessions: false }" \
-X POST http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/shutdown
{
  // response does not include a 'return' property since it's a void operation
}

Example 3-5 non-void operation with an argument: String getURL(String protocol)

curl ... -d "{ protocol: 'http' }" \
-X POST http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/getURL
{
  return: "http://localhost:7003"
}

Using Queries

The REST API includes a powerful bulk access capability that lets you dynamically describe a tree of beans that can be returned in one call.

Each tree (for example, edit, domain runtime, and such), has a root search resource. You can POST a query to these search resources. The query indicates which beans (and properties and links) should be returned, and, as such, returns a portion ("slice") of the bean tree.

Bulk access can only be used for reading; it cannot be used for writing.

Search Resources

Each bean tree includes a search resource for bulk queries.

On the Administration Server:

URL Description

.../management/weblogic/latest/edit/search

Returns a slice of the edit bean tree (in progress edits that have not been saved to disk yet).

.../management/weblogic/latest/domainConfig/search

Returns a slice of the last configuration bean tree that was saved to disk (versus the configuration the servers are currently using).

.../management/weblogic/latest/domainRuntime/search

Returns a slice of the Administration Server's domain runtime bean tree (which covers all the servers' runtime bean trees).

.../management/weblogic/latest/serverConfig/search

Returns a slice of the Administration Server's configuration bean tree (the configuration the Administration Server is running against).

.../management/weblogic/latest/serverRuntime/search

Returns a slice of the Administration Server's runtime bean tree.

On Managed Servers:

URL Description

.../management/weblogic/latest/serverConfig/search

Returns a slice of Managed Server's configuration bean tree (the configuration the server is running against).

.../management/weblogic/latest/serverRuntime/search

Returns a slice of the Managed Server's runtime bean tree.

When you POST a query to a search resource, the query starts searching at the root bean of the tree. The resource returns a JSON response containing the results of the query, that "slice" of the bean tree.

Object Queries

An object query describes what data should be returned for a WLS bean (or collection of beans), such as:

  • Which of the bean's properties should be returned.

  • Which of the bean's links should be returned.

  • Which of the bean's children should be returned.

  • For a collection, which of its children should be returned.

Note that all searches start at the root bean of the search resource's tree. For example, if you POST a query to management/weblogic/latest/domainRuntime/search, it starts searching at the DomainRuntimeMBean in the domain runtime tree.

Fields and ExcludeFields

fields specifies which bean properties (for example, scalars and references) are returned. It is a JSON string array of property names. For example, to return the domain's name and configurationVersion:

curl ... -d "{ fields: [ 'name', 'configurationVersion' ] }" \
-X POST http://localhost:7001/management/weblogic/latest/edit/search

If the query lists properties that the bean does not support, then that part of the query is ignored (instead of returning an error). If fields is not specified, then all of the properties are returned.

excludeFields specifies a list of fields that should not be returned; all other properties are returned. fields and excludeFields are mutually exclusive.

Note that a query's fields and excludeFields properties mirror the fields and excludeFields query parameters that you can specify when calling GET on a resource. The difference is that the query parameters use comma-separated names and queries use JSON arrays of names.

Links and ExcludeLinks

links specifies which of the bean's links should be returned. It is a JSON string array of link rel names. For example, to return the domain's self and servers links:

curl ... -d "{ links: [ 'self', 'servers' ] }" \
-X POST http://localhost:7001/management/weblogic/latest/edit/search

If the query lists links that the bean does not support, then that part of the query is ignored (instead of returning an error).

If links is not specified, then all the links are returned (except for collection children, which only return their self and canonical links by default).

Similarly, excludeLinks specifies a list of links that should not be returned; all other links are returned. links and excludeLinks are mutually exclusive.

To return all of a collection's children's links, use excludeLinks: [].

Note that a query's links and excludeLinks properties mirror the links and excludeLinks query parameters that you can specify when calling GET on a resource.

Children

children specifies which child bean properties are returned. It is a JSON object whose property names are the names of the children to return, and whose values are object queries. For example, to get the domain's name, along with the name and listen port of each server:

curl ... -d "{
  fields: [ 'name' ], // only return the domain's name
  children: {
    servers: { // fetch the domain's 'servers' collection
      fields: [ 'name', 'listenPort' ] // only return each server's name and listen port
    }
  }
}" -X POST http://localhost:7001/management/weblogic/latest/edit/search

If children is not specified, then none of the bean's children are returned.

Identities

Sometimes you want to only return certain items in a collection (for example, myserver and Server-0). Each collection child has a property that specifies its identity. Typically this is the name property. The query uses this property name to specify which children of a collection are returned. It is a JSON string array of identities. fields and links can also be used to control which properties and links are returned for each of these children. For example, to return the name and listen port for the servers, Server-0 and Server-1:

curl ... -d "{
  fields: [ 'name' ], // only return the domain's name
  children: {
    servers: { // fetch the domain's 'servers' collection
      names: [ 'Server-0', 'Server-1' ], // only return the children whose 'name' is 'Server-0' or 'Server-1'
      fields: [ 'name', 'listenPort' ] // only return each server's name and listen port
    }
  }
}" -X POST http://localhost:7001/management/weblogic/latest/edit/search

Identities that do not exist are ignored (instead of returning an error). Similarly, if the context is not a collection, then this part of the query is ignored. By default, all collection children are returned.

Response Body

The response body follows the usual pattern (inline properties or items, depending on whether the URL is for a bean or a collection). The child beans are returned as nested properties. For example:

curl ... -d "{
  fields: [], // don't return any domain level properties
  links: [], // don't return any domain level links
  children: {
    servers: { // fetch the domain's 'servers' collection
      names: [ 'Server-0', 'Server-1' ], // only return the children whose 'name' is 'Server-0' or 'Server-1'
      fields: [ 'name' ], // only return each server's name
      links: [], // don't return any per-server links
      children: {
        SSL: {
          fields: [ 'listenPort' ], // only return each server's SSL listen port
          links: [] // don't return any SSL level links
        }
      }
    }
  }
}" -X POST http://localhost:7001/management/weblogic/latest/edit/search
{code:JavaScript}
HTTP/1.1 200 OK
{
  servers: {
    items: [
      {
        name: "myserver",
        SSL: { listenPort: 7002}
      },
      {
        name: "AnotherServer",
        SSL: { listenPort: 7002}
      }
    ]
  }
}

Query Examples

This example gets the component runtimes of specific applications on all running servers. It only returns the name for the server runtimes and application runtime parents and returns all of the component runtimes' properties.

curl ... -d "{
  fields: [], links: [], // don't return any domain runtime level properties or links
  children: {
    serverRuntimes: {
      fields: [ 'name' ], links: [], // return each server's name.  don't return any server level links
      children: {
        applicationRuntimes: {
          name: [ 'myapp', 'BasicApp' ], // only return apps 'myapp' and 'BasicApp'
          fields: [ 'name' ], links: [], // return each app's name but no per-app links
          children: {
            componentRuntimes: { links: [] } // return all component runtime properties, but no links
          }
        }
      }
    }
  }
}" -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search

This example gets all of the servlet runtime and EJB runtime information for a set of applications across all running servers.

curl ... -d "{
  links: [],
  fields: [],
  children: {
    serverRuntimes: {
      links: [],
      fields: [ 'name', 'state' ],
      children: {
        applicationRuntimes: {
          name: [ 'myapp', 'BasicApp' ],
          links: [],
          fields: [ 'name', 'healthState' ],
          children: {
            componentRuntimes: {
              links: [],
              fields:[
                'name',
                'healthState',
                'contextRoot',
                'openSessionsCurrentCount',
                'sessionsOpenedTotalCount'
              ],
              children: {
                EJBRuntimes: {
                  links: [],
                  fields: [
                    'EJBName',
                    'type'
                  ],
                  children: {
                    transactionRuntime: {
                      links: [],
                      fields: [
                        'transactionsCommittedTotalCount',
                        'transactionsRolledBackTotalCount',
                        'transactionsTimedOutTotalCount'
                      ]
                    },
                    poolRuntime: {
                      links: [],
                      fields: [
                        'accessTotalCount',
                        'missTotalCount',
                        'destroyedTotalCount',
                        'pooledBeansCurrentCount',
                        'beansInUseCurrentCount',
                        'waiterCurrentCount',
                        'timeoutTotalCount'
                      ]
                    },
                    cacheRuntime: {
                      links: [],
                      fields: [
                        'cachedBeansCurrentCount',
                        'cacheAccessCount',
                        'cacheMissCount',
                        'activationCount',
                        'passivationCount'
                      ]
                    },
                    lockingRuntime: {
                      links: [],
                      fields: [
                        'lockEntriesCurrentCount',
                        'lockManagerAccessCount',
                        'waiterTotalCount',
                        'waiterCurrentCount',
                        'timeoutTotalCount'
                      ]
                    },
                    timerRuntime: {
                      links: [],
                      fields: [
                        'timeoutCount',
                        'cancelledTimerCount',
                        'activeTimerCount',
                        'disabledTimerCount'
                      ]
                    }
                  }
                },
                servlets: {
                  links: [],
                  fields: [
                    'servletName',
                    'contextPath',
                    'reloadTotalCount',
                    'invocationTotalCount',
                    'executionTimeTotal',
                    'executionTimeHigh',
                    'executionTimeLow'
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}" -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search

Limiting the Wait Time For a Delegated Request

When you make a GET request or a search POST call in the domainRuntime tree that gets delegated to one or more servers, you can specify the requestMaxWaitMillis query parameter which sets the maximum amount of time you are willing to wait for a response from each server. If not specified, it uses the RestfulManagementServicesMBean's DelegatedRequestMaxWaitMillis value that the administrator configured for the domain.

For servers that do not respond fast enough, the response body includes bad per-server HTTP status codes.

Examine the following examples:

# GET all the server runtimes' names, give up on a server if it doesn't respond within 10 milliseconds:
curl -v \
--user admin:admin123 \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-X GET http://127.0.0.1:7001/management/weblogic/latest/domainRuntime/serverRuntimes?links=none\&fields=name\&requestMaxWaitMillis=10

< HTTP/1.1 200 OK
{"items": [
    {
        "httpStatus": 504,
        "name": "Cluster1Server1",
        "identity": []
    },
    {"name": "AdminServer"},
    {
        "httpStatus": 504,
        "name": "Cluster1Server2",
        "identity": []
    }
]}

# GET all the server runtimes' application's names, give up on a server if it doesn't respond within 50 milliseconds:
curl -v \
--user admin:admin123 \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-X POST http://127.0.0.1:7001/management/weblogic/latest/domainRuntime/search?requestMaxWaitMillis=50 \ -d "{
   links: [], fields: ['name'],
   children: {
     serverRuntimes: {
       links: [], fields: ['name'],
       children: {
         applicationRuntimes: { links: [], fields: ['name'] }
       }
     }
   }
}"

< HTTP/1.1 200 OK
{
    "name": "bean-ex",
    "serverRuntimes": {"items": [
        {
            "httpStatus": 504,
            "name": "Cluster1Server1",
            "identity": []
        },
        {
            "name": "AdminServer",
            "applicationRuntimes": {"items": [
                {"name": "bea_wls_management_internal2"},
                {"name": "jms-internal-xa-adp"},
                {"name": "mejb"},
                {"name": "jms-internal-notran-adp"},
                {"name": "bea_wls_internal"},
                {"name": "wls-management-services"},
                {"name": "bea_wls_deployment_internal"}
            ]}
        },
        {
            "httpStatus": 504,
            "name": "Cluster1Server2",
            "identity": []
        }
    ]}
}

Consolidating Search Results

You can consolidate the domainRuntime search results of REST resources that span multiple servers in a domain based on criteria you specify, for example, you can retrieve the maximum openSocketsCurrentCount of all the running servers.

Like any search, you use the request body to specify a slice of the bean tree to return. To enable this feature, you specify additional fields to indicate that the results should be consolidated across the servers and how each property should be consolidated.

Review the syntax for the following consolidated search examples:

----------------------------------------------------------------------
Get the total number of open sessions across each application's component runtimes across all servers
----------------------------------------------------------------------

curl -v \
--user monitor:monitor123 \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
  links: [], fields: [],
  children: {
    serverRuntimes: {
      mergeCollection: true,
      children: {
        applicationRuntimes: {
          mergeOn: 'name',
          fields: [ { name: 'name', sameValue: true } ],
          children: {
            componentRuntimes: {
              mergeCollection: true,
              fields: [ { name: 'openSessionsCurrentCount', total: true } ]
            }
          }
        }
      }
    }
  }
}" \
-X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search

HTTP/1.1 200 OK

Response Body:
{"serverRuntimes": {"items": [{"applicationRuntimes": {"items": [
    {
        "name": "JDBCDataSource1",
        "componentRuntimes": {"items": [{}]}
    },
    {
        "name": "bea_wls_deployment_internal",
        "componentRuntimes": {"items": [{"openSessionsCurrentCount": {
            "total": 0,
            "count": 3
        }}]}
    },
    {
        "name": "wls-management-services",
        "componentRuntimes": {"items": [{"openSessionsCurrentCount": {
            "total": 202,
            "count": 3
        }}]}
    },
    {
        "name": "bea_wls_cluster_internal",
        "componentRuntimes": {"items": [{"openSessionsCurrentCount": {
            "total": 0,
            "count": 2
        }}]}
    },
    {
        "name": "jms-internal-xa-adp",
        "componentRuntimes": {"items": [{}]}
    },
    {
        "name": "fairShare",
        "componentRuntimes": {"items": [{"openSessionsCurrentCount": {
            "total": 0,
            "count": 2
        }}]}
    },
    {
        "name": "bea_wls_internal",
        "componentRuntimes": {"items": [{"openSessionsCurrentCount": {
            "total": 0,
            "count": 3
        }}]}
    },
    {
        "name": "JMSSystemResource1",
        "componentRuntimes": {"items": [{}]}
    },
    {
        "name": "basicapp",
        "componentRuntimes": {"items": [{"openSessionsCurrentCount": {
            "total": 0,
            "count": 2
        }}]}
    },
    {
        "name": "jms-internal-notran-adp",
        "componentRuntimes": {"items": [{}]}
    },
    {
        "name": "bea_wls_management_internal2",
        "componentRuntimes": {"items": [{"openSessionsCurrentCount": {
            "total": 0,
            "count": 1
        }}]}
    },
    {
        "name": "mejb",
        "componentRuntimes": {"items": [{}]}
    }
]}}]}}

----------------------------------------------------------------------
Get the total number of invocations of the servlets of each component runtime of the fairShare and wls-management-services applications across all servers
----------------------------------------------------------------------

curl -v \
--user monitor:monitor123 \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d "{
  links: [], fields: [],
  children: {
    serverRuntimes: {
      mergeCollection: true,
      children: {
        applicationRuntimes: {
          name: [ 'fairShare', 'wls-management-services' ],
          mergeOn: 'name',
          fields: [ { name: 'name', sameValue: true } ],
          children: {
            componentRuntimes: {
              mergeOn: 'moduleId',
              fields: [ { name: 'contextRoot', sameValue: true } ],
              children: {
                servlets: {
                  mergeCollection: true,
                  fields: [ { name: 'invocationTotalCount', total: true } ]
                }
              }
            }
          }
        }
      }
    }
  }
}" \
-X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search

HTTP/1.1 200 OK

Response Body:
{"serverRuntimes": {"items": [{"applicationRuntimes": {"items": [
    {
        "name": "fairShare",
        "componentRuntimes": {"items": [{
            "contextRoot": "\/fairShare",
            "servlets": {"items": [{"invocationTotalCount": {
                "total": 0,
                "count": 8
            }}]}
        }]}
    },
    {
        "name": "wls-management-services",
        "componentRuntimes": {"items": [{
            "contextRoot": "\/management",
            "servlets": {"items": [{"invocationTotalCount": {
                "total": 202,
                "count": 9
            }}]}
        }]}
    }
]}}]}}

The first example, "Get the total number of open sessions across each application's component runtimes across all servers,” keeps each application separate (based on the application's name), merging each application's components together across all the servers.

This is achieved by specifying:

   serverRuntimes - mergeCollection: true
     applicationRuntimes - mergeOn: 'name'
       componentRuntimes - mergeCollection: true

For example, if the bean tree has:

  server1
    app1 : comp1, comp2
    app2 : comp3, comp4
    app3 : comp5, comp6

  server2
    app1 : comp1, comp2
    app2 : comp3, comp4
    app3 : comp5, comp6

The response will return:

app1
    comp
      merged values from server1.app1.comp1, server1.app1.comp2, server2.app1.comp1, server2.app1.comp2
  
app2
    comp
      merged values from server1.app2.comp3, server1.app2.comp4, server2.app2.comp3, server2.app2.comp4
  
app3
    comp
      merged values from server1.app3.comp5, server1.app3.comp6, server2.app3.comp5, server2.app3.comp6

The second example, "Get the total number of invocations of the servlets of each component runtime of the fairShare and wls-management-services applications across all servers," keeps each application separate (based on the application's name), and keeps each application's components separate (based on the component's moduleId), merging each application's component's servlets together across all the servers. It also specifies to return results only for app1 and app2 (versus all the applications).

This is achieved by specifying:

  serverRuntimes - mergeCollection: true
    applicationRuntimes - mergeOn: 'name', name: [ 'app1', 'app2' ]
      componentRuntimes - mergeOn: 'moduleId'
        servlets - mergeCollection: true

For example, if the bean tree has:

  server1
    app1
      comp1 : servlet1, servlet2
      comp2 : servlet3, servlet4
    app2
      comp3 : servlet5, servlet6
      comp4 : servlet7, servlet8
    app3
      comp5 : servlet9, servlet10
      comp6 : servlet11, servlet12

  server2    
    app1
      comp1 : servlet1, servlet2
      comp2 : servlet3, servlet4
    app2
      comp3 : servlet5, servlet6
      comp4 : servlet7, servlet8
    app3
      comp5 : servlet9, servlet10
      comp6 : servlet11, servlet12

The response will return (notice that app3 isn't returned):

  app1
    comp1
      merged values from server1.app1.comp1.servlet1, server1.app1.comp1.servlet2, server2.app1.comp1.servlet1, server2.app1.comp1.servlet2
    comp2
      merged values from server1.app1.comp2.servlet3, server1.app1.comp2.servlet4, server2.app1.comp2.servlet3, server2.app1.comp2.servlet4
  app2
    comp3
      merged values from server1.app2.comp3.servlet5, server1.app2.comp3.servlet6, server2.app2.comp3.servlet5, server2.app2.comp3.servlet6
    comp4
      merged values from server1.app2.comp4.servlet7, server1.app2.comp4.servlet8, server2.app2.comp4.servlet7, server2.app2.copm4.servlet8

For more examples of consolidating search results in domains, see Domain Level REST API Examples.

Request Body Merge-Related Fields

The following table describes the request body merge-related search fields. If none are specified, then the search results will not be consolidated.
Field Description

mergeCollection

Indicates that a collection of MBeans (and their trees of sub-MBeans) should be merged together into a single consolidated MBean tree (and tree of sub-MBeans).  Its value is a Boolean.

mergeOn

Indicates when child MBeans in a merged collection should be merged together (for example, that app1 in server1 should be merged with app1 in server2). Its value is a string, naming a property.

mergeOn must be specified for all child collections of a merged collection (unless mergeCollection: true is specified for the child collection instead). Similarly, it must not be specified on collections that are is not parented by a merged collection. Returns BAD REQUEST if either condition is violated.

fields

Specifies which properties of an MBean should be returned. fields contains a list of per-property merge rules. If not specified, no properties are returned. Each entry in the list of fields is a JSON object containing the name of the property and its merge rules. For example:

fields: [ { name: 'openSessionCurrentCount', total: true, min:true, max:true }, { name: 'type', sameValue: true } ]

Multiple merge rules can be specified for the same property (for example, return the min, max, and total). Returns BAD REQUEST if no merge rules are specified for a property. See the Per-Property Merge Rules table below.

excludeFields

Specifies which properties should not be returned when doing a non-consolidated search (for example, a list of what not to return instead of what to return). It is not supported when doing consolidated searches. Returns BAD REQUEST if present.

links

links and excludeLinks specify which links to related REST resources are returned when doing a non-consolidated search.  They are not supported when doing a consolidated search. Returns BAD REQUEST if either is present.

Per-Property Merge Rules

The following table describes the per-property merge rules.

Field Description

name

Contains the name of the property to merge. It is a mandatory string field. Returns BAD REQUEST if it is not specified.

total

min

max

The total field indicates that the sum and number of the property values should be returned. Similarly, the min and max fields indicate that the minimum or maximum property value should be returned. These are optional Boolean fields which default to false.

Returns BAD REQUEST if the REST API finds a value that is not a number (or a string that can be converted to a number).

sameValue

Some property values should be the same on each merged MBean, for example, a component's type and moduleId. The sameValue field indicates that the value should be the same for each merged MBean. It is an optional Boolean field which defaults to false.

Returns BAD REQUEST if the REST API finds different values while merging. Similarly, returns BAD REQUEST if the property value is not a string.

values

Indicates that the list of property values should be returned. They are unordered. The field is an optional Boolean which defaults to false. It can be used for any type of MBean property.

About Synchronous and Asynchronous Operations

Several MBean operations (for example, server lifecycle, deployment) are asynchronous. They return job MBeans that must be monitored to determine when the job has completed.

Asynchronous MBean operations return a 200 OK, 201 Created or 400 Bad Request if the operation completed or failed immediately. Otherwise, they return a 202 Accepted and you must poll the returned job resource to find out when the work is done. By default, REST makes a best effort attempt to wait for the work to complete, but returns after about 5 minutes. You can specify the Prefer header to control how long REST waits for the work to complete.

Table 3-1 describes using the Prefer header.

Table 3-1 Using the Prefer Header

Header Description

-X Prefer:respond-async

The client polls a returned job resource. REST returns a 200 OK, 201 Created, or 400 Bad Request if the asynchronous MBean operation finishes immediately; otherwise it returns a 202 Accepted.

-X Prefer:wait=#

For example, -X Prefer:wait=10

The REST resource internally polls the job for up to the specified number of seconds and returns a 200 OK, 201 Created, or 400 Bad Request if the asynchronous MBean operation finishes within that time; otherwise it returns a 202 Accepted, along with a Location header containing the URL of a REST task resource that the client can poll (via GET) to find out when the work is done.

If you don't specify the Prefer header, REST will return a 200 OK, 201 Created, or 400 Bad Request if the asynchronous MBean operation finishes within approximately 5 minutes, otherwise it returns a 202 Accepted.

If you specify both respond-async and wait, respond-async is ignored.

For examples of synchronous and asynchronous operations, see Domain Level REST API Examples.

Deploying Applications and Libraries

You view deployed applications and libraries in the edit tree. You call POST on the collections to deploy them, and DELETE to undeploy them.

Similarly, the deployment MBeans take server relative pathnames. In addition, you can upload files from the client to the server then deploy them and use create form resources to inspect deployments (for example, to determine their preferred name and version numbers). For examples of deploying domain-scoped applications, see Domain Level REST API Examples.

Cross-Origin Resource Sharing (CORS) for WebLogic Server REST APIs

As of 14.1.1.0.0, WebLogic Server RESTful management services support client-side Cross-Origin Resource Sharing (CORS).

CORS is a security mechanism that uses additional HTTP headers to allow a web application running in one domain or origin to access a resource or retrieve data from a different domain, thus enabling a cross-domain request. The RESTful management service endpoints of the WebLogic REST API include new headers that are used for CORS control. You can configure the CORS HTTP header values to handle HTTP requests that are made to the WebLogic Server REST endpoints. See Modify This Restful Management Service in RESTful Edit Management Interface for Oracle WebLogic Server.

The following table describes the CORS configuration parameters that you can use to handle HTTP requests:

CORS Parameters Description

CORSEnabled

Specifies if the support for CORS (Cross-Origin Resource Sharing) processing in the RESTful management services web application is enabled.

The default value is false.

CORSAllowedOrigins

Specifies a list of allowed origins for CORS requests. When specified, the HTTP Origin header must exactly match one of the values configured as allowed. If it does not match the Origin header, then the browser rejects the request. When the list is empty or not specified and CORS support is enabled, then all origins are accepted by default.

CORS origin values include protocol, domain name, and may also include port numbers.

CORSAllowedCredentials

Determines if your server allows the use of credentials by using cookies. The default value is false.

CORSAllowedHeaders

Specifies a list of HTTP header names that are allowed for CORS requests. The default setting allows all headers.

CORSAllowedMethods

Specifies a list of HTTP methods that are allowed for CORS requests. The default setting allows all methods.

CORSExposedHeaders

Specifies a comma-separated list of HTTP header names to be exposed to the browser. The default setting does not specify any specific headers.

CORSMaxAge

Indicates the time, in seconds, for which the CORS preflight request results can be cached.

The default setting does not specify any value.