2.3 What URI Mappings are Available and How do They Work?

Any REST API makes use of existing HTTP methods, such as GET and POST requests, to trigger various operations. The type of operation that is triggered depends on the HTTP method and the URI pattern that is used.

In Oracle VM, URI patterns are built around ObjectType names and the identifier for a particular instance of the ObjectType. In three cases, an identifier for an instance can be omitted:

Creation of a new instance of an ObjectType, using the HTTP POST method.
Full listing of all instances of an ObjectType, using the HTTP GET method.
Listing of the identifiers for all instances of an ObjectType, using the HTTP GET method.

The different ObjectTypes that can be accessed via the API are described in the full API documentation provided in the SDK. Note that ObjectType names may not map perfectly onto objects that you are used to seeing in the Oracle VM Manager Web Interface or Oracle VM Manager Command Line Interface. For instance, the 'resourceGroup' object is the same thing as a 'tag' in UI or CLI nomenclature. These differences are usually mentioned within the API documentation accompanying the SDK.

Since many objects within Oracle VM Manager have parent-child relationships, URI mappings are available to create, query and delete these relationships.

This table contains the basic URI patterns to interact with the available objects controlled by Oracle VM Manager:

Operation	HTTP Method	URI Path	Entity Passed In	Return Type
Create	POST	/ObjectType	Object being created	Job
Get all	GET	/ObjectType		List<ObjectType>
Get all IDs	GET	/ObjectType/id		List<SimpleId>
Get by ID	GET	/ObjectType/{id}		ObjectType
Modify	PUT	/ObjectType/{id}	Object being modified	Job
Delete	DELETE	/ObjectType/{id}		Job
Action ^[a]	PUT	/ObjectType/{id}/action	Object being created	Job
Add child association	PUT	/ObjectType/{id}/addChildType	Child ID	Job
Remove child association	PUT	/ObjectType/{id}/removeChildType	Child ID	Job
Get child associations	GET	/ObjectType/{id}/ChildType		List<ChildType>
Get child association IDs	GET	/ObjectType/{id}/ChildType/id		List<SimpleId>
Create child object	POST	/ParentType/{id}/ChildType	New ChildType object	Job
Delete child object	DELETE	/ParentType/{parentId}/ChildType/{childId}		Job
^[a] See Section 2.6.8, “Managing Servers in a Server Pool” for two good examples of action-style activities.

Note

Capitalization as shown in the sample URIs is significant for the actual URI request: ObjectTypeNames are capitalized, while actions are not.
Actions available for an ObjectType vary depending on the ObjectType. Each action available for each ObjectType is described in the documentation provided with the SDK.
Only top level objects are removed using the Delete operation. For child objects, use the Delete child object operation.
If an object can exist outside the association of its parent it is created as a normal object and then added to the parent using the Add child association operation. The relationship between ServerPool and Server objects is an example of this. If the parent object is deleted, the child still exists.
If the child object cannot exist without its parent then it is created via a Create child object operation. The relationship between Vm and VmDiskMapping objects is an example of this. In this case, if the parent object is deleted, the child is also be deleted.

Tip

For GET type requests you can test out the REST API directly by using a standard web browser, as long as you have a means to modify the HTTP Request Headers to include the HTTP Basic authentication credentials required to access the API. If you are using Mozilla Firefox, you could try the Modify Headers Add-On; while Google Chrome users could avail of the ModHeaders Extension.

Modify your browser headers to include the Authorization header. Set the value to BASIC and append the Base64 encoded string for your username and password in the format: username:password. Once this is done, you can simply point your browser at any URL that accepts a GET request. For example, to obtain a listing of server IDs, try pointing your browser at https://hostname:7002/ovm/core/wsapi/rest/Server/id where hostname is the IP address or FQDN of the Oracle VM Manager host.