Items represent nodes in the Verve graph. This can have a type Requirement, a Verification Event, or even a Folder, Component, or File.

Endpoints and Data Structures

GET endpoints and parameters

Endpoints

  • To access a list of all Items within a project: GET /item/pid/<project_id>

    • Acceptable query parameters are:

      • groupid=<group_id>: This only returns items that are a member of the specified Group ID

      • rtype=<relationship_type>: This restricts what upstream and downstream items are populated in the parents and children arrays. Can be sent multiple times.

      • filter_string=<text string>: This works as a simple text search across an item’s Title and Body strings, and only returns items that match the text filter. Case insensitive

  • To access information about a specific Item: GET /item/did/<item_id>

Response Parameters

Parameter

Data Type

Description

did

integer, primary_key

The ID or “Data Identifier” of the item returned.

title

string

Title of the Item returned.

body

string

Detailed description of the Item returned. Intended for modification.

rendered

string

Rendered description of the Item returned, having rendered any Atomics tags and replaced them with their corresponding values.

type

string

Description of a specific Item Type. These can be customized to your deployment, but commonly used items are:

  • Requirement

  • Verification

  • Folder

  • Component

timestamp

timestamp

Timestamp of most recent modification.

locked

boolean

Whether or not this item is locked from being edited.

atomics

Atomics[]

List of atomics associated with the Item. See the section on Atomics for details.

approvals

Approvals[]

List of approvals associated with the Item. In format:

  • Approval ID (int)

  • Approval State (enum: requested, approved, abstained, rejected)

  • Timestamp (timestamp)

  • User (userid, user status, display name, avatar URL)

For a deeper understanding, please see Verve Review & Approval Process and https://futureeng.atlassian.net/wiki/pages/resumedraft.action?draftId=1625423931

approval_state

enum approval_state

Computed approval state based on approval statuses. For a deeper understanding, please see Verve Review & Approval Process | Data-Model

children

array

List of children downstream from the item. In format:

  • did (int): data ID of the downstream item.

  • rtype (enum): Relationship type of the downstream item.

  • title (string): Title of the downstream item.

parents

array

List of parents upstream from the item. In format:

  • did (int): data ID of the upstream item.

  • rtype (enum): Relationship type of the upstream item.

  • title (string): Title of the upstream item.

verification_status

enum verification_status

One of four values:

  • unverified

  • in_progress

  • verified

  • failed

computed_verification_status

enum verification_status

Computed verification state based on verification statuses. For a deeper understanding, please see Status Icons. Same enumeration as verification_status

group_list

array

List of groups the item is a member of.

  • display_name (string): Name of group

  • id (int): ID of group

POST and PUT endpoints and parameters

Endpoints

  • To create a new item: POST /item

  • To update a specific item: PUT /item/did/<item_id>

  • To delete an item: DELETE: /item/did/<item_id>

Body Parameters

Parameter

Datatype

Required

Description

title

string

No

Short-form title text

body

string

No

Long-form description text of the item in question.

locked

boolean

No

If the item is locked for editing.

If already set to true, then the only acceptable body parameter in this request is false.

project_id

integer

No

ID of project item is a member of.

type_id

integer

No

Integer corresponding to specific Item Type. These can be customized to your deployment, but commonly used items are:

  • Requirement: 2

  • Verification: 19

  • Folder: 25

  • Component: 24

verification_status

enum verification_status

No

One of four values:

  • unverified

  • in_progress

  • verified

  • failed

Examples