This section describes the Oracle WebLogic Server 12.1.3 RESTful management resources.
The RESTful management resources provide a comprehensive public interface for configuring, monitoring, and administering the Oracle WebLogic Server platform in all supported environments.
Note:
The URL format for REST management APIs has changed in 12.1.3. The URL format introduced in 12.1.2 will continue to work, but is deprecated in this release of WebLogic Server.To use RESTful management services in a WebLogic Server domain, your WebLogic Administrator must enable them using the WebLogic Server Administration Console. For more information, see "Enable RESTful Management Services" in the Administration Console Online Help. Alternatively, using WebLogic Scripting Tool (WLST), set the RestfulManagementService Enabled property on the DomainMBean.
The format of the WebLogic Server resource URL is:
http(s)://host:port/management/wls/{version}/path
where:
host—the host where WebLogic Server is running
port—the HTTP or HTTPS port
{version}—the version of a REST resource. See "The {version} Specifier in Resource URLs".
path—the relative path that identifies a resource. For example, the path to a server instance would be: servers/id/myserver.
The {version} specifier in resource URLs implicitly (/latest) or explicitly (/12.1.3.0) denotes the version of a REST resource. In future WLS releases, you can specify /latest to use the current version of a REST resource or a version number to specify a previous version.
As a best practice, if you are using a browser or a reflexive client that follows links in the resources for navigation and can react to evolving resources, then use /latest. If you are writing code that would break as a resource evolves, then specify an explicit version.
The WebLogic Server RESTful Management Services support the following representation formats:
The data format that can you get back from a resource (for example, through the Accept header) – only JSON.
The data format that can you send in to a resource (for example, through the Content-Type header) – most support only JSON, however, some also support multi-part forms (for example, the file upload versions of deploying applications and libraries).
The WebLogic Server REST interfaces support methods for accessing objects in the configuration and monitoring object trees.
Table 1-1 shows the REST methods for administering monitoring and configuration data and the tasks that you can perform with each method.
Table 1-1 REST Resource Methods for Administering Configuration Data
| Task | REST Method |
|---|---|
|
Determine the methods and method parameters that an object in the tree supports. |
|
|
Retrieve data for an object in the tree. |
|
|
Add an object to the tree. |
|
|
Update an object in the tree. |
|
|
Delete an object from the tree. |
|
Use the following procedures with WebLogic Server REST resources.
To create a new entity:
Invoke OPTIONS to get a template object containing default values for the new entity.
Change the values of any properties you want to customize on the returned object.
POST the modified object to create the new entity.
To change some properties of an entity:
Invoke GET on the entity's URL to get back an object containing the entity's current values.
Change the values of the properties you want to modify on the returned object.
POST the modified object back to the entity's URL.
For long running operations, specify the __detached=true query parameter (asynchronous invocation). The method runs in detached (background) mode and returns immediately after launching the job. Otherwise, it waits for the job to complete, fail, or timeout (synchronous invocation).
Specify _includeFields and _excludeFields query parameters to constrain the fields included in a response. Filtering collection results to only the information that you require may yield faster response times when interacting with large data sets. Include and exclude are mutually exclusive, and if neither is specified, all available information is included.
Use multi-part form data to pass a stream of bytes from the client to the WLS resource. For example, when the files you want to deploy (or redeploy) are not on the Administration Server file system. Use the POST accepting "multipart/form-data" method to upload the files from the client's file system to the Administration Server and then deploy (or redeploy) them.
The WebLogic Server REST interfaces support navigating the resource tree dynamically. To provide this support, the GET method on each REST resource returns a links element containing a list of URIs to the resources above and below it in the resource tree. Thus, you can navigate the resource tree using this technique:
Make an HTTP GET request on a known REST resource, specifying a literal, hard-coded value as the URI.
Parse the links list in the response to identify the appropriate parent or child resource. See "Parsing the links List" for more information.
If you are done navigating and the REST resource you identified in Step 2 is the one on which you want to perform operations, use the appropriate HTTP requests to perform the operations, using the URI value you retrieved from the links list.
If you need to continue navigating the resource tree, make an HTTP GET request on the REST resource you identified in Step 2, using the URI value you retrieved from the links list. Then, return to Step 2.
Using dynamic navigation of the resource tree can provide a variety of benefits, including:
More maintainable source code, because it does not include a literal, hard-coded URI value for each HTTP request.
The ability to perform actions across collections of objects, such as servers and applications, whose names are not known during code development.
The links element returned as part of the response to an HTTP GET request is a list of subordinate elements, each describing a single resource that is directly related to the current resource. Each of these subordinate elements contains the following properties:
A string value indicating how the linked resource is related to the current resource. The string values are as follows:
The linked resource is the parent of the current resource.
The linked resource performs an action on the object represented by the current resource. The value of the title property indicates the type of action the linked resource performs.
A string without dots (.). The linked resource has a relationship to the current resource that is specific to the current resource. For example, the GET method on the /management/wls/{version} resource returns link list elements with simple-name values corresponding to the types of objects in a domain:
changemanger
datasources
deployments
jobs
servers
targets
A string containing one dot(.). The linked resource is a member of a collection of resources subordinate to the current resource, and another element in the GET response provides more information about the linked resource. An example of such a collection is the individual servers under the /management/wls/{version}/servers resource.
The first part of the dotted-name value is the name of a list element in the GET response that contains more information, and the second part is the name of the property in that list element's subelement that identifies each subelement:
list-element-name.subelement-property-name
To discover more information about the linked resource, use its dotted-name value in conjunction with its title value:
Parse the dotted-name value into its two parts: list-element-name and subelement-property-name.
In the GET response, look for a list element named list-element-name. In this list, look for a subelement whose subelement-property-name property value matches the linked resource's title property value.
For example, given the dotted-name value items.name and the title value myserver, you would look in the GET response for the subelement of the items list whose name property value is the string myserver.
A string value containing the URI to use in an HTTP request to access the linked resource.
(Optional) A string value providing additional information when the rel property value is action or dotted-name:
When rel property value is action, the title property value describes the kind of action the linked resource performs.
When the rel property value is dotted-name, the title property value is the value to match in the subelement property of the list element specified by the dotted-name value.
The HTTP methods used to manipulate the resources described in this section all return one of the following HTTP status codes:
The request was successfully completed. A 200 is returned for successful GET or OPTIONS methods, or a POST method to modify a resource (versus create).
The request has been fulfilled and resulted in a new resource being created. A Location header containing the canonical URI for the newly created resource will be returned.
A 201 is returned from a synchronous resource creation or an asynchronous resource creation that completed before the response was returned.
The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
When specifying an asynchronous (__detached=true) resource creation, (such as when deploying an application) or update (such as when redeploying an application), a 202 is returned if the operation is still in progress. If __detached=false, a 202 might still be returned if the underlying operation does not finish in a reasonable amount of time.
The response contains a Location header of a job resource that the client should poll to find out when the job has finished. Also, it returns an entity that contains the current state of the job.
The request could not be processed because it contains missing or invalid information (such as a validation error on an input field, a missing required value, or such).
The request is not authorized. The authentication credentials included with this request are missing or invalid.
Cannot authenticate the user. The user does not possess authorization to perform this request.
The request specified a URI of a resource that does not exist.
The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this request URI.
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.
The client's ContentType header is wrong (for example. the client tries to send in XML but the resource can only accept JSON).
The server encountered an unexpected condition which prevented it from fulfilling the request.
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.