Searches

You can retrieve cloud objects by using the following methods:

• Use the API pattern GET /csm/<class>/guid to retrieve a specific object.
• Use the API pattern GET /csm/<class>/<guid>/(<relation>)+ to retrieve a relationship with a specific object.
• Use the API pattern POST /csm/<class>/search to retrieve objects of a particular class.

The search request API patterns accept either a fillFields or ignoreFields parameter that you can use to specify which attributes and relationships to return. The request parameter, which is optional, contains a comma separated list of attribute or relation names. Each search request returns a JSON document that contains the retrieved objects.

For example, the following request retrieves a list of virtual hosts that are associated with a specific virtual cluster:

The request returns a JSON document that contains a list of VirtualHost objects, where only the name, guid, and hostName attributes are present.

Sometimes, instead of enumerating the fields you want to view, you might prefer to enumerate the fields to ignore. That takes the form of the ignoreFields request parameter. It should never be used with the fillFields parameter.

If you do not include a fillFields or ignoreFields parameter, the resulting JSON document includes all attributes and greedy relationships.

Timeouts

A request may specify a timeout on the search. If the search completes before the timeout, the POST call will return a response body with the resulting list of objects. Otherwise, it will return a Task after the timeout, and the task will use normal task management (polling or callbacks) to complete.

Paging

There are two ways to retrieve lists of objects via the API, either a GET that traverses a list of relations, or a POST search request. In both cases, the URL may specify a request parameter that describes the page size, and a request parameter that specifies the page number. There is no context kept between calls. Therefore, a call to get page 1 might return overlapping objects with a call to retrieve page 2 if the data changed between calls.

The paging request parameters are: pageSize and pageNumber. Set the pageSize value to -1 to return all objects with no pagination. Page numbering starts at 0.

Sorting

For search or list get calls you can specify a request parameter that names an attribute to sort by. Depending on the data type of the attribute, appropriate sorting will apply (lexicographical sort for strings, and so on). The request parameter is called sortBy.