Item List API

Note: This API is under development and may change without notice.

Managing Item Lists

1. List all Item Lists
2. Get an Item List
3. Update an Item List
4. Delete an Item List
5. Create a new Item List
6. Create a new version of an existing Item List

Managing Item List contents

1. Search for Items
2. Get an Item
3. Update an Item
4. Create an Item
5. Delete an Item

List the Item Lists in a Project

GET /api/projects/:pid/itemlists

Returns an array of all the Item Lists in the specified Project. Only the latest version of each Item List is returned.

Get an Item List

GET /api/projects/:pid/itemlists/:id

Retrieves a specific Item List.

Response

{
  ItemListID: 12,   // The Item List's unique ID
  Name: 'My list',  // The Item List's name
  Version: 3,       // The Item List's version number,
  Status: 3,        // The Item List's status (1 = Draft, 3 = Active)
  RootItemListID: 1 // The ID of version 1 of this Item List
}

Update an existing Item List

PUT /api/projects/:pid/itemlists/:id

Updates the properties of an existing Item List

Request body

{
  Name: 'My list',         // The name of the Item List
  VariesByAttributeID: 99  // The Target AttributeID that defines the categories that this Item List varies by
}

Note: Once an Item List has been defined as variable and activated for the first time, it is not possible to switch it between normal and variable by changing the VariesByAttributeID.

Delete an existing Item List

DELETE /api/projects/:pid/itemlists/:id

Deletes the specified Item List.

Note: It is not possible to delete active Item Lists.

Create a new Item List

POST /api/projects/:pid/itemlists

Creates an entirely new Item List.

Request body

{
  Name: 'My item list',     // The name of the Item List
  VariesByAttributeID: null // The Target Attribute ID that this Item List will vary by, or null otherwise
}

Create a new version of an existing Item List

POST /api/projects/:pid/itemlists/:id?[empty=true]

Creates a new version of an existing Item List, optionally copying the contents.

Note: If the current version of the Project's Questionnaire references the original Item List, then it will be automatically updated to reference the new version of the Item List, potentially creating a new version of the Questionnaire if the current version has already been activated.

Request parameters

empty - If true then the new version will be created empty. If false then the contents of the original Item List will be copied into the new version.

Managing Item List contents

Search for Items

GET /api/projects/:pid/itemlists/:lid/items?[output=:output]&[sort=:sort]

Searches for Items matching the specified criteria and returns a [Paged Result](Paged Result).

Request parameters

• Item.Name - A wildcarded string that the Item's name must match.
• ItemAttribute.AttributeName - A wildcarded string that the Item's AttributeName attribute must match.
• output - A comma separated list of Item fields to include in the output. By default just Item.ItemID is included.
• sort - A comma separated list of Item fields to sort by. Fields are sorted in ascending order unless a - is appended to the field name.

Eg:

GET /api/projects/1/itemlists/2/items?ItemAttribute.Manufacturer=Acme&output=Item.ItemID,Item.Name&sort=Item.Name-

Item field names

• Item.ItemID - The Item's ID.
• Item.Name - The Item's name.
• ItemAttribute.AttributeName - The Item's AttributeName attribute.

Get an Item

GET /api/projects/:pid/itemlists/:lid/items/:id

Update an Item

PUT /api/projects/:pid/itemlists/:lid/items/:id

Create an Item

POST /api/projects/:pid/itemlists/:lid/items

Adds an Item to an Item List.

Request body

{
  ItemID: null,            // If null then a new Item will be created. Otherwise this existing Item will be added
  Name: "My new item",     // The Item's name, or null if adding an existing Item
  Attributes:              // The Item's Attributes, or null if adding an existing Item
  {
    "Manufacturer": "Acme"
  }
}

Note 1: It is not possible to modify the contents of active Item Lists.
Note 2: TeamHaven assumes that Items only belong in one chain of Item Lists (eg, all versions). Care should be taken to ensure that you don't add an existing Item to different Item Lists.

Delete an Item

DELETE /api/projects/:pid/itemlists/:lid/items/:id

Deletes an Item from an Item List.

Note: It is not possible to modify the contents of active Item Lists.