This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
dev:sapi:get_item_info [2022/04/20 17:46] – created vikki | dev:sapi:get_item_info [2022/04/20 18:08] (current) – vikki | ||
---|---|---|---|
Line 4: | Line 4: | ||
====== GetItemInfo ====== | ====== GetItemInfo ====== | ||
- | **Script path:** < | + | **Script path:** < |
- | **Description: | + | **Description: |
- | **INPUT (via GET or POST)** | + | ---- |
- | Mandatory parameters are: \\ | + | ===== INPUT (via GET or POST) ===== |
- | Optional parameters are: | + | |
+ | Mandatory parameters are: **sid, path**\\ | ||
+ | Optional parameters are: **fields, ofmt** | ||
+ | |||
+ | |||
+ | ==== sid ==== | ||
+ | Session id of the login user. [mandatory] | ||
+ | |||
+ | |||
+ | ==== path ==== | ||
+ | Path to a folder. [mandatory]\\ | ||
+ | Please refer to [[dev: | ||
+ | |||
+ | Path must point to an existing folder. E.g.: | ||
+ | * < | ||
+ | * < | ||
+ | |||
+ | |||
+ | ==== fields ==== | ||
+ | = name, | ||
+ | = name, | ||
+ | |||
+ | The field names may be any order and the returned field values will follow that order. Separate the field names with commas but do not include any spaces. Fields obmitted will not be returned. Returned value for a field can be empty strings. If a field does not exist in the item's information record, an empty field is returned. WARNING: a misspelled field name will be quietly ignored, i.e. returned empty value! | ||
+ | |||
+ | * **name** is the name of the item | ||
+ | * **date** is in 14-digit form, corrected to user's localtime using the user's timezone info from his profile. e.g. 20010130052533 | ||
+ | * **dategmt** is in 14-digit form, GMT time. e.g. 20010129212533 is the GMT equivalent to the date example. | ||
+ | * **mtime** is the number of non-leap seconds since 1 Jan 1970 GMT. mtime is in GMT. | ||
+ | * **size** is the file size. Integer, no commas. For folders, it is the total size of all files and subfolder under it, BUT it can be -1 or " | ||
+ | * **type** is a string ' | ||
+ | * **owner** is the owner of the item, taking the form of < | ||
+ | * **company** is the organization of owner, taking the form of [< | ||
+ | * **lock** is the lock status of the item. Value is ' | ||
+ | * **description** is a string entered by owner to describe the item. | ||
+ | * **checksum** is the 128-bit MD5 checksum of the file represented as lowercased 32 hex digits. This only applies to files. WARNING: For folders, the value returned will be empty/null, without any errors being flagged. | ||
+ | * **lock_owner** is the lock owner for a lock placed on the item. Value is in the form of and " | ||
+ | * **ucar** is the JSON object the represents the UCAR settings associated with this item. Currently only applicable to folders in Company Share and Company HomePage. For folders elsewhere and regular files, the value returned is empty. An example of such a JSON object is documented in an example below, as the value of the property " | ||
+ | |||
+ | ==== ofmt ==== | ||
+ | Output format\\ | ||
+ | = json means to return output in JSON format (with minimum or no redundant white spaces)\\ | ||
+ | = jsonp means to return ouput in JSON format, pretty-printed for easy human readability. | ||
+ | otherwise (default, or not specified), means the legacy " | ||
+ | |||
+ | In the legacy " | ||
+ | In a JSON output formt, the returned value for ucar is also a JSON object nested in overall JSON object, and can be pretty-printed as requested. | ||
+ | |||
+ | ---- | ||
+ | |||
+ | ===== Legacy " | ||
+ | |||
+ | Successful return: | ||
+ | true < | ||
+ | <tab separated field values for the item> < | ||
+ | |||
+ | e.g. | ||
+ | |||
+ | true | ||
+ | newfolder <TAB> 20010206180115 <TAB> 0 <TAB> folder | ||
+ | |||
+ | Unsuccessful return: | ||
+ | false <tab> <error message> < | ||
+ | |||
+ | e.g. | ||
+ | |||
+ | false <TAB> Item does not exist. | ||
+ | |||
+ | ---- | ||
+ | |||
+ | ===== JSON OUTPUT (content-type: | ||
+ | |||
+ | Successful return: | ||
+ | |||
+ | JSON output object: | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | } | ||
+ | Most of field values will be represented simply as " | ||
+ | For field value of " | ||
+ | " | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | : | ||
+ | } | ||
+ | |||
+ | Unsuccessful return: | ||
+ | |||
+ | JSON output object: | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | |||
+ | In both legacy " | ||
+ | e.g. 200 OK, 401 Invalid user profile, etc. | ||
+ | |||
+ | |||
+ | A full sample of a JSON object returned: | ||
+ | |||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | } | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | } | ||
+ | |||
+ | For a brief explanation of what the ucar settings mean, first note that ucar only applys to a folder item (and in a shared folder like Company Share or Company HomePage). The JSON object has as first level of name/value pairs keyed on ucar tasks names like " | ||