We use curl in our API documentation to show an example how to form REST API calls, and it is not meant to be an actual production example of implementation.
You have core objects, which represent domain objects for specific business goals and related objects which contain related information or collections of information. Related objects are often simplified representations of core objects but are not implicitly core objects. For example, the tags collection on Asset is a simpler form of the Tag core object, but the ports collection is not.
Collections of related objects are found within a container object called a QList. These lists will have a specific name for the type of objects they contain. For example, the tags collection Asset is a TagSimpleQList and will read and write TagSimple API objects. These lists can contain a number of sub elements.
count - (Read only) The total number of items returned in the list element
list - (Read only) The items contained in the collection on the server
set - A new collection of items to place in the server side object. Any existing items not in the list provided will be discarded.
add - A new item to be added to the server side object. The item may be keyed of one ore more fields depending on the collection. In the even that that an item in the add collection collides with an existing entry, the existing entry will be updated with the fields provided. Many collections will allow you to either associate an existing item with the targeted collection, or create a new one and add it to the collection. If you provide a key field, most often id or uuid, the object will be looked up and associated. In the absence of these fields, a new object will be created (if the list allows it).
remove - Removes an element from the list by the collections key, usually id. If the item does not exist, the entry will be ignored. Additional fields beyond the item key will also be ignored.
update - Updates item(s) in the collection. This allows you to update the fields of non-core items via the objects and reference them. Items will be resolved by the collection’s key, and then additional fields applied to the found object. In the event that the supplied item does not match an existing related object, it will be ignored.
Whitespace (which includes line breaks) is not allowed in XML tags that are numbers.
Invalid tag - This syntax will not work
Valid tag - This syntax will work just fine
Some API actions will return a list of core objects but will limit the number returned (default is 100). You can change which objects are returned and the number of objects by specifying a preferences tag in the POST body of your request.
Preferences tag fields:
startFromOffset - The first item to return by index. The default is 1.
startFromId - The first item to return by primary key. No default value.
limitResults - The total number of items to return. The default is 100.
The allowed methods, POST and/or GET, for each API request are documented with each API call in this user guide.
Sample pagination settings
Use the optional “fields” parameter for any Search or Get API request to limit the amount of information returned in the results. Simply specify the fields you want to include in the output, and all other information will be filtered out. Multiple fields are comma separated and wildcards are supported.
This get request will fetch tag ID 12345 and return the tag ID, name and creation date:
Sample limit results
This search request will return the ID of the connector and the ID of any default tags attached to the connector:
Sample search connectors
Using wildcards, the example above could be represented as:
Sample search connectors using wildcards