There are two main ways to get a list of items in a workspace. You can use the items endpoint or the query endpoint. In this article, I will be comparing and contrasting these API calls. (Spoiler Alert: My preference is the query endpoint)
The items endpoint follows the standard REST pattern. You make a GET call to a collection URL ( /api/v2/workspaces/{workspaceId}/items). The return value is all items in the workspace. The return value is a set of Item objects, which just provide basic information. Because the payload is simple, the API call is fast.
At first, this endpoint seems like an ideal way to navigate workspaces, but there are some big downsides. For one, the endpoint will return deleted Items. This is because “deleted” Items are not actually removed from the system. Instead, they are just tagged as deleted. The endpoint makes no assumptions about what type of item you want to get, so it returns both deleted and non-deleted Items.
The items endpoint also doesn’t have any sort or filter capability. In a large workspace, this is a significant drawback. If you are looking for a specific item, you may have to scan through hundreds of pages in order to find it.
The query endpoint is meant to give you more control over what you get back. It lets you sort your results and lets you filter out Items you don’t want. There is an article on how to query over on the PLM 360 online help. One common use is to filter out deleted items and sort by the descriptor name, like in this example JSON.
| { "conditions":[ { "propertyDefinition": { "id":"IS_DELETED", "type":"SYSTEM" }, "operator":"EQUALS", "value":"false" }], "page":1, "pageSize":100, "sort":[ { "propertyDefinition": { "id":"ITEM_DESCRIPTOR", "type":"SYSTEM" }, "sortAscending":true }] } |
The return value is a set of ItemDetail objects. It contains more data than an Item, but at the cost of performance. Currently, the query endpoint has no way to control which parts of the ItemDetail are returned. So it always attempts to look up the field values, ownership and audit data.
This call is a bit harder to work with because it’s a POST call. Since a payload has to be passed in, the GET verb can’t be used. You can’t easily test it out in your web browser, and it’s harder to cycle through pages.
Although the query endpoint is slower, it’s still the one I recommend using for your apps. The flexibility and scalability are a must-have. There will likely be improvements in the future, so don't be too discouraged if it doesn't yet support the type of search you want. The only time I suggest using the items endpoint is to do a quick scan of the entire workspace.
Leave a Reply