GuidesREST APISlack CommunitySupport PortalOpsview 6.8+ Documentation

Config - Request Format

Config endpoint request details

URL: /rest/config/{object_type}

  • GET - list object type. Can pass in search attributes
  • POST - add a new object or a list of object type
  • PUT - create or update (based on unique keys) object or a list of objects
  • DELETE - delete a list of objects. Only implemented for host object type. Unimplemented for all other object types

URL: /rest/config/{object_type}/{id}

  • GET - get object details
  • POST - clone this object with merged incoming data to create new object
  • PUT - update this object's details
  • DELETE - delete object

URL: /rest/config/{object_type}/exists?name={name}

  • GET - get object existential status

Updating a single object

When POST or PUTting a single object, the API expects a hash input with key value pairs. If successful, the API will return back the new serialised object.

All ref attributes are ignored when updating - the ref key is for clients that may want further information about the foreign object.

Updating a list of objects

When POST or PUTting a list of objects, the API expects a hash with a key of list which is an array of hash objects. Each object will then be POST or PUT in turn.

If successful, the data returned will be of the format:

{
   "objects_updated" : 3
}

There is an extra parameter that can be used:

  • synchronise - this means that any objects left after the individual PUTs will be deleted

The whole request is wrapped in a transaction. If there is a failure for any item, a rollback will occur and no changes will have been made to the system. The response will be:

{
   message:"Rollback. Error trying to synchronise object: 2",
   detail:"detail about the error",
   objects_updated:0
}

Deleting a list of objects

Example:

DELETE /rest/config/OBJECTTYPE?id=X&id=Y&id=Z

This expects a list of ids as parameters of the objects to delete. Will return a 400 error if no ids are specified (as it is dangerous to delete everything).

You can also use "s.id" as the parameter name, for consistency with the GET /rest/config/OBJECTTYPE REST API.

If you have a long list of ids which could potentially hit the URL query string length, you can use the x-tunneled-method to tunnel the DELETE verb inside a POST request and set body parameters with the id values.

On success, will return HTTP status 200 with: 

{ "objects_deleted": X }

On failure to delete an object, the whole transaction will be rolled back and will return HTTP status 400 with the standard error and detail response:

{
  "message": "Cannot delete as object still in use",
  "detail": ....
}