/api/get_equipment details Parameter Explained

Field REST API call, /api/get_equipment, allows you to retrieve equipment records. It has a parameter “details” which, in the API reference page, read as follows:

details : string – Whether to retrieve equipment details, or just header information (e.g. ‘some’, ‘more’, ‘none’)

I find this description vague. From an internal discussion, I learned that there is details = ‘all’ option as well, which isn’t documented. So I decided to experiment these options for details parameter. I thought sharing my observation here with sample outputs might clarify the meaning of these options.

First, /api/get_equipment takes two required parameters: ticket and project_id. Below are in addition to these two.

Case 1.  no optional parameter

When no optional parameter is given, the call returns every record including deleted ones. If a record is from a deleted one, it is indicated by the value of “deleted” field shown as “true”. Otherwise, “false”. (See the field circled in blue in the image below.)

If you observe each record, it includes all the fields, but fields in a form of list do not include value. (See the image below.  A part circled in orange indicates empty lists.)

2015_0825_getEquipmentDetailsParameter_case_1

Case 2.  details = all

If you want to retrieve all the information, including list items (such as, custom field values), you can use details = “all”. The image below shows that the records has custom_field_values and audits, which wasn’t available by default with no parameter.

2015_0825_getEquipmentDetailsParameter_case_2a.png2015_0825_getEquipmentDetailsParameter_case_2b.png

Case 3. details = more

This option retrieves fields which have a list form only. This compliments Case1, where you don’t get list fields; i.e., details all = details none + details more.

2015_0825_getEquipmentDetailsParameter_case_3.png

Case 4. details = some

This wasn’t clear to me till I finally noticed the difference after combining with equipment_ids. This returns all the equipment. But detail level will differ depending on if you specified equipment_ids or not.  You will get more detailed info for those whose ids are specified with equipment_ids. Otherwise, short list. e.g.,

detail = “some”
equipment_ids = “xxxx-xxx-xxxx,yyyy-yyy-yyyy”

In this case, two equipment, “xxxx-xxx-xxxx” and “yyyy-yyy-yyyy” will have detailed info. while others will be short listing.

Case 5. Partial listing

If you want to retrieve only a part of equipment records, you can set equipment_ids with comma (,) separated list of ids together with ids_only flag set to “1”. e.g.,

equipment_ids = “xxxx-xxx-xxxx,yyyy-yyy-yyyy”
ids_only = “1”;

Note that if we use ids_only, you actually get more info, same as using details = “all”.

Case 6.  details = none

As we seen in the case 5 above, if we retrieved equipment records partially, it returns all the info by default.  If you want only short info listing with partial retrieval, you can set details to “none”.

details = “none”
equipment_ids = “xxxxx-xxx-xxxx,yyyy-yyy-yyyy”
ids_only = “1”;

I hope this clarify the meaning of details.

Mikako

Advertisements

One thought on “/api/get_equipment details Parameter Explained

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s