REST API (TECH PREVIEW)

JBoss Operations Network 3.1

The web path for the REST interface, unless otherwise specified, is http://localhost:7080/rest/1

June 12, 2012

Abstract

This is an API reference for the REST interface for JBoss Operations Network.

Important

This REST API is under active development. While some interfaces are probably stable (such as resources and metrics methods), some interfaces are still being designed and could change significantly as development progresses (such as the alerts methods). As with all preview technologies, expect significant changes in subsequent releases of the REST API. Compatibility is not guaranteed, so use caution when developing clients using the tech preview version of the JBoss ON REST API.

1. /alert: Deal with Alerts

This API deals with alerts that have fired. It does not offer to create/update AlertDefinitions (yet)

Defining class: org.rhq.enterprise.server.rest.AlertHandlerLocal

1.1. GET alert/

Table 1. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
page	Query	Page number	false	int	all	0
status	Query	Limit to status, UNUSED AT THE MOMENT	false	java.lang.String	all

Return type: java.util.List<org.rhq.enterprise.server.rest.domain.AlertRest>

1.2. GET alert/{id}

Table 2. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the alert to retrieve	true	int	all

Return type: org.rhq.enterprise.server.rest.domain.AlertRest

1.3. PUT alert/{id}

Table 3. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the alert to acknowledge	true	int	all

Return type: org.rhq.enterprise.server.rest.domain.AlertRest

1.4. DELETE alert/{id}

Table 4. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the alert to remove	true	int	all

Return type: void

1.5. GET alert/{id}/definition

Table 5. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the alert to show the definition	true	int	all

Return type: org.rhq.enterprise.server.rest.domain.AlertDefinitionRest

1.6. GET alert/definition

Table 6. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
page	Query	Page number	false	int	all	0
status	Query	Limit to status, UNUSED AT THE MOMENT	false	java.lang.String	all

Return type: java.util.List<org.rhq.enterprise.server.rest.domain.AlertDefinitionRest>

1.7. GET alert/definition/{id}

Table 7. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the alert definition to retrieve	true	int	all

Return type: org.rhq.enterprise.server.rest.domain.AlertDefinitionRest

2. /configurationHistory

Defining class: org.rhq.enterprise.server.rest.reporting.ConfigurationHistoryLocal

2.1. GET configurationHistory/

This method has no parameters

Return type: javax.ws.rs.core.StreamingOutput

3. /driftCompliance

Defining class: org.rhq.enterprise.server.rest.reporting.DriftComplianceLocal

3.1. GET driftCompliance/

Table 8. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
resourceTypeId	Query	none	false	java.lang.String	all	-none-
version	Query	none	false	java.lang.String	all	-none-

Return type: javax.ws.rs.core.StreamingOutput

4. /group: Deal with groups

API that deals with resource groups

Defining class: org.rhq.enterprise.server.rest.GroupHandlerLocal

4.1. GET group/

This method has no parameters

Return type: javax.ws.rs.core.Response

4.2. GET group/{id}

Table 9. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the group	true	int	all

Return type: javax.ws.rs.core.Response

4.3. POST group/

Table 10. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
-body-	A GroupRest object containing at least a name for the group	false	org.rhq.enterprise.server.rest.domain.GroupRest	all

Return type: javax.ws.rs.core.Response

4.4. PUT group/{id}

Table 11. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the group to update	true	int	all
-body-	New version of the group	false	org.rhq.enterprise.server.rest.domain.GroupRest	all

Return type: javax.ws.rs.core.Response

4.5. DELETE group/{id}

Table 12. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the group to delete	true	int	all

Return type: javax.ws.rs.core.Response

4.6. GET group/{id}/resources

Table 13. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the group to retrieve the resources for	true	int	all

Return type: javax.ws.rs.core.Response

4.7. PUT group/{id}/resource/{resourceId}

Table 14. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the existing group	true	int	all
resourceId	Path	Id of the resource to add	true	int	all

Return type: javax.ws.rs.core.Response

Table 15. Error Codes
Code	Reason
404	If there is no resource or group with the passed id
409	Resource type does not match the group one

4.8. DELETE group/{id}/resource/{resourceId}

Table 16. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the existing group	true	int	all
resourceId	Path	Id of the resource to remove	true	int	all

Return type: javax.ws.rs.core.Response

5. /inventorySummary

Defining class: org.rhq.enterprise.server.rest.reporting.InventorySummaryLocal

5.1. GET inventorySummary/

Table 17. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
resourceTypeId	Query	none	false	java.lang.String	all	-none-
version	Query	none	false	java.lang.String	all	-none-

Return type: javax.ws.rs.core.StreamingOutput

6. /metric: Deal with metrics

This part of the API deals with exporting metrics

Defining class: org.rhq.enterprise.server.rest.MetricHandlerLocal

6.1. GET metric/data/{scheduleId}

Table 18. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
scheduleId	Path	Schedule Id of the values to query	true	int	all
startTime	Query	Start time since epoch	false	long	all
endTime	Query	End time since epoch	false	long	all
dataPoints	Query	Number of buckets - currently fixed at 60	false	int	all	60
hideEmpty	Query	none	false	boolean	all	-none-

Return type: javax.ws.rs.core.Response

Table 19. Error Codes
Code	Reason
404	No schedule with the passed id exists

6.2. GET metric/data

Table 20. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
sid	Query	none	false	java.lang.String	all	-none-
startTime	Query	none	false	long	all	-none-
endTime	Query	none	false	long	all	-none-
dataPoints	Query	none	false	int	all	-none-
hideEmpty	Query	none	false	boolean	all	-none-

Return type: javax.ws.rs.core.Response

6.3. GET metric/data/resource/{resourceId}

Table 21. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
resourceId	Path	Resource to query	true	int	all

Return type: java.util.List<org.rhq.enterprise.server.rest.domain.MetricAggregate>

Table 22. Error Codes
Code	Reason
404	If no resource with the passed id exists

6.4. GET metric/schedule/{id}

Table 23. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Schedule Id	true	int	all

Return type: javax.ws.rs.core.Response

Table 24. Error Codes
Code	Reason
404	No schedule with the passed id exists

6.5. PUT metric/schedule/{id}

Table 25. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the schedule to query	true	int	all
-body-	New schedule data	true	org.rhq.enterprise.server.rest.domain.MetricSchedule	all

Return type: MetricSchedule

Table 26. Error Codes
Code	Reason
404	No schedule with the passed id exists

6.6. GET metric/data/{scheduleId}/raw

Table 27. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
scheduleId	Path	none	true	int	all
startTime	Query	Start time since epoch	false	long	all	Now - 8h
endTime	Query	End time since epoch	false	long	all	Now
duration	Query	Timespan in ms	false	long	all	8h = 28800000ms

Return type: javax.ws.rs.core.StreamingOutput

Table 28. Error Codes
Code	Reason
404	No schedule with the passed id exists

6.7. PUT metric/data/{scheduleId}/raw/{timeStamp}

Table 29. Parameters
Name	P.Type	Description	Required	Type	Allowed values
scheduleId	Path	Id of the schedule	true	int	all
timeStamp	Path	Timestamp of the metric	true	long	all
-body-	Data point	true	org.rhq.enterprise.server.rest.domain.NumericDataPoint	all

Return type: javax.ws.rs.core.Response

Table 30. Error Codes
Code	Reason
404	No schedule with the passed id exists

6.8. POST metric/data/raw

Table 31. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
points	-body-	none	false	java.util.Collection<org.rhq.enterprise.server.rest.domain.NumericDataPoint>	all	-none-

Return type: javax.ws.rs.core.Response

6.9. GET metric/data/{scheduleId}/baseline

Table 32. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
scheduleId	Path	Id of the schedule	true	int	all

Return type: org.rhq.enterprise.server.rest.domain.Baseline

Table 33. Error Codes
Code	Reason
404	No schedule with the passed id exists

6.10. PUT metric/data/{scheduleId}/baseline

Table 34. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
scheduleId	Path	Id of the schedule	true	int	all
baseline	-body-	none	false	org.rhq.enterprise.server.rest.domain.Baseline	all	-none-

Return type: void

Table 35. Error Codes
Code	Reason
404	No schedule with the passed id exists

6.11. PUT metric/data/{scheduleId}/trait

Table 36. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
scheduleId	Path	Id of the schedule	true	int	all
value	-body-	none	false	org.rhq.enterprise.server.rest.domain.StringValue	all	-none-

Return type: javax.ws.rs.core.Response

Table 37. Error Codes
Code	Reason
404	No schedule with the passed id exists

6.12. GET metric/data/{scheduleId}/trait

Table 38. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
scheduleId	Path	Id of the schedule	true	int	all

Return type: StringValue

Table 39. Error Codes
Code	Reason
404	No schedule with the passed id exists

7. /operation

Defining class: org.rhq.enterprise.server.rest.OperationsHandlerLocal

7.1. GET operation/definition/{id}

Table 40. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	none	true	int	all	-none-
resourceId	Query	none	false	java.lang.Integer	all	-none-

Return type: javax.ws.rs.core.Response

7.2. GET operation/definitions

Table 41. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
resourceId	Query	none	false	java.lang.Integer	all	-none-

Return type: javax.ws.rs.core.Response

7.3. POST operation/definition/{id}

Table 42. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	none	true	int	all	-none-
resourceId	Query	none	false	java.lang.Integer	all	-none-

Return type: javax.ws.rs.core.Response

7.4. GET operation/{id}

Table 43. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	none	true	int	all	-none-

Return type: javax.ws.rs.core.Response

7.5. PUT operation/{id}

Table 44. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	none	true	int	all	-none-
operation	-body-	none	false	org.rhq.enterprise.server.rest.domain.OperationRest	all	-none-

Return type: javax.ws.rs.core.Response

7.6. DELETE operation/{id}

Table 45. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	none	true	int	all	-none-

Return type: javax.ws.rs.core.Response

7.7. GET operation/history/{id}

Table 46. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	none	true	java.lang.String	all	-none-

Return type: javax.ws.rs.core.Response

8. /platformUtilization

Defining class: org.rhq.enterprise.server.rest.reporting.PlatformUtilizationLocal

8.1. GET platformUtilization/

This method has no parameters

Return type: javax.ws.rs.core.StreamingOutput

9. /recentAlerts

Defining class: org.rhq.enterprise.server.rest.reporting.RecentAlertLocal

9.1. GET recentAlerts/

Table 47. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
alertPriority	Query	none	false	java.lang.String	all	high,medium,low
startTime	Query	none	false	java.lang.Long	all	-none-
endTime	Query	none	false	java.lang.Long	all	-none-

Return type: javax.ws.rs.core.StreamingOutput

10. /recentDrift

Defining class: org.rhq.enterprise.server.rest.reporting.RecentDriftLocal

10.1. GET recentDrift/

Table 48. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
categories	Query	none	false	java.lang.String	all	-none-
snapshot	Query	none	false	java.lang.Integer	all	-none-
path	Query	none	false	java.lang.String	all	-none-
definition	Query	none	false	java.lang.String	all	-none-
startTime	Query	none	false	java.lang.Long	all	-none-
endTime	Query	none	false	java.lang.Long	all	-none-

Return type: javax.ws.rs.core.StreamingOutput

11. /recentOperations

Defining class: org.rhq.enterprise.server.rest.reporting.RecentOperationsLocal

11.1. GET recentOperations/

Table 49. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
status	Query	none	false	java.lang.String	all	inprogress,success,failure,canceled
startTime	Query	none	false	java.lang.Long	all	-none-
endTime	Query	none	false	java.lang.Long	all	-none-

Return type: javax.ws.rs.core.StreamingOutput

12. /resource: Resource related

This endpoint deals with single resources, not groups

Defining class: org.rhq.enterprise.server.rest.ResourceHandlerLocal

12.1. GET resource/{id}

Table 50. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the resource to retrieve	true	int	all

Return type: ResourceWithType

Table 51. Error Codes
Code	Reason
404	If no resource with the passed id exists

12.2. GET resource/platforms

This method has no parameters

Return type: ResourceWithType

12.3. GET resource/{id}/hierarchy

Table 52. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the resource to start with	true	int	all

Return type: ResourceWithType

Table 53. Error Codes
Code	Reason
404	If no resource with the passed id exists

12.4. GET resource/{id}/availability

Table 54. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the resource to query	true	int	all

Return type: org.rhq.enterprise.server.rest.domain.AvailabilityRest

Table 55. Error Codes
Code	Reason
404	If no resource with the passed id exists

12.5. PUT resource/{id}/availability

Table 56. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the resource to update	true	int	all
-body-	New Availability setting	true	org.rhq.enterprise.server.rest.domain.AvailabilityRest	all

Return type: void

12.6. GET resource/{id}/schedules

Table 57. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the resource to obtain the schedules for	true	int	all
type	Query	Limit by type	false	java.lang.String	<empty>, all, metric, trait, measurement	all
enabledOnly	Query	Limit by enabled schedules	false	boolean	all	true
name	Query	Limit by name	false	java.lang.String	all

Return type: MetricSchedule

Table 58. Error Codes
Code	Reason
404	If no resource with the passed id exists

12.7. GET resource/{id}/children

Table 59. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the resource to get children	true	int	all

Return type: javax.ws.rs.core.Response

Table 60. Error Codes
Code	Reason
404	If no resource with the passed id exists

12.8. GET resource/{id}/alerts

Table 61. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the resource to query	true	int	all

Return type: java.util.List<org.rhq.enterprise.server.rest.domain.Link>

Table 62. Error Codes
Code	Reason
404	If no resource with the passed id exists

12.9. POST resource/platform/{name}

Table 63. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
name	Path	Name of the platform	true	java.lang.String	all
-body-	Type of the platform	false	org.rhq.enterprise.server.rest.domain.StringValue	Linux,Windows,... TODO

Return type: javax.ws.rs.core.Response

12.10. POST resource/{name}

Table 64. Parameters
Name	P.Type	Description	Required	Type	Allowed values
name	Path	Name of the new resource	true	java.lang.String	all
-body-	Name of the Resource tpye	false	org.rhq.enterprise.server.rest.domain.StringValue	all
plugin	Query	Name of the plugin providing the type	false	java.lang.String	all
parentId	Query	Id of the future parent to attach this to	false	int	all

Return type: javax.ws.rs.core.Response

13. /status: Provide system status information

Defining class: org.rhq.enterprise.server.rest.StatusHandlerLocal

13.1. GET status/

This method has no parameters

Return type: javax.ws.rs.core.Response

14. /suspectMetrics

Defining class: org.rhq.enterprise.server.rest.reporting.SuspectMetricLocal

14.1. GET suspectMetrics/

This method has no parameters

Return type: javax.ws.rs.core.StreamingOutput

15. /user: API that deals with user related stuff

Defining class: org.rhq.enterprise.server.rest.UserHandlerLocal

15.1. GET user/favorites/resource

This method has no parameters

Return type: java.util.List<org.rhq.enterprise.server.rest.domain.ResourceWithType>

15.2. PUT user/favorites/resource/{id}

Table 65. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the resource	true	int	all

Return type: void

15.3. DELETE user/favorites/resource/{id}

Table 66. Parameters
Name	P.Type	Description	Required	Type	Allowed values	Default value
id	Path	Id of the resource	true	int	all

Return type: void

16. /alertDefinitions: The Alert definitions report

Defining class: org.rhq.enterprise.server.rest.reporting.AlertDefinitionLocal

16.1. GET alertDefinitions/

This method has no parameters

Return type: javax.ws.rs.core.StreamingOutput

Legal Notice

This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.