Skip to main content

rest-1.v1 Endpoints

The rest-1.v1 family of endpoints provides core asset manipulation capabilities including create, read, update, delete (CRUD) operations, asset history retrieval, and new asset templates.

Overview​

The rest-1.v1 endpoints form the foundation of the Digital.ai Agility REST API, available since version 7.1 (Spring 2007). These endpoints support XML serialization and use REST syntax with Asset Type and ID encoded in the URL.

Comparison with query.v1​

Featurerest-1.v1/Dataquery.v1
OperationsRead, write, update, deleteRead-only
Asset ScopeOne root Asset Type per HTTP callArbitrarily nested master/detail relationships
Multiple QueriesSingle query per HTTP transactionMultiple independent queries in one transaction
SerializationXMLJSON (simple name-to-value mapping)
Query SyntaxREST syntax with URL encodingYAML or JSON (human-readable)
Available Since7.1 (Spring 2007)13.2 (Summer 2013)
  • query.v1 - Read-only queries with JSON responses
  • meta.v1 - Metadata about asset types and definitions

rest-1.v1/Data​

This endpoint provides create, read, update, and delete operations for assets.

FieldValue
URL Form<Server Base URI>/rest-1.v1/Data/<Asset Type>[/<OID>]
AuthenticationApplication
HTTP Request VerbGET, POST
Response Content Typetext/xml

HTTP Verbs​

HTTP GET​

GET requests query information and receive an XML response.

HTTP POST​

POST requests update information and include an XML payload describing the update. POST requests also execute operations that change data in ways not possible with simple updates (such as re-opening a closed story).

Update Operations​

Update a Simple Attribute​

Update a value type on an asset by marking the attribute with act="set" and filling in the new value in the element's text.

Example: Update the Phone attribute

POST /VersionOne/rest-1.v1/Data/Member/20 HTTP/1.1
Content-Type: application/xml

<Asset>
  <Attribute name="Phone" act="set">555-555-1212</Attribute>
</Asset>

Response:

<Asset href="/VersionOne/rest-1.v1/Data/Member/20/173" id="Member:20:173">
  <Attribute name="Phone">555-555-1212</Attribute>
</Asset>

Update a Single-Value Relationship​

Update a single-value relationship by marking the attribute with act="set" and filling in the idref with the referenced OID Token.

Example: Change the Owner of the root project

POST /VersionOne/rest-1.v1/Data/Scope/0 HTTP/1.1
Content-Type: application/xml

<Asset>
  <Relation name="Owner" act="set">
    <Asset idref="Member:20" />
  </Relation>
</Asset>

To unset a single-value relationship, pass an empty element:

POST /VersionOne/rest-1.v1/Data/Scope/0 HTTP/1.1
Content-Type: application/xml

<Asset>
  <Relation name="Owner" act="set">
  </Relation>
</Asset>

Update a Multi-Value Relationship​

Update multi-value relationships by marking enclosed Asset elements with act="add" or act="remove" and filling in the idref with the referenced OID Token.

Example: Add and remove members from the root project

POST /VersionOne/rest-1.v1/Data/Scope/0 HTTP/1.1
Content-Type: application/xml

<Asset>
  <Relation name="Members">
    <Asset idref="Member:1000" act="add"/>
    <Asset idref="Member:1001" act="remove"/>
  </Relation>
</Asset>

rest-1.v1/Hist​

This endpoint provides read-only access to asset history by returning moments (point-in-time snapshots).

FieldValue
URL Form<Server Base URI>/rest-1.v1/Hist/<from>
AuthenticationApplication
HTTP Request VerbGET
Response Content Typetext/xml

Request Parameters​

  • asof - Query parameter for point-in-time queries
  • Filter - Query parameter to filter results
  • findin - Query parameter for searching within results
  • find - Query parameter for text search
  • from - Starting asset or scope
  • group - Grouping criteria
  • op - Operation parameter
  • page - Pagination parameter
  • select - Attribute selection
  • sort - Sort order
  • where - Filter criteria
  • with - Include related assets

HTTP Verbs​

HTTP GET​

GET requests query historical information and receive an XML response containing moments.

Usage Notes​

Use this endpoint to:

  • Retrieve complete change history for assets
  • Perform point-in-time queries using the asof parameter
  • Track who changed what and when
  • Audit asset modifications

For activity streams (which may not contain every change), use the ActivityStream endpoint instead.

rest-1.v1/New​

This endpoint provides templates for creating new assets. A new asset template contains suggested attribute values that can be modified before posting to rest-1.v1/Data to create the asset.

FieldValue
URL Form<Server Base URI>/rest-1.v1/New/<asset type>?ctx=<OID Token>
AuthenticationApplication
HTTP Request VerbGET
Response Content Typetext/xml

Context Parameter​

When creating a new asset in the "context" of another asset, some attributes carry over from the context asset. For example, creating a new Story in the context of a Request carries over the Name, Description, Scope, and creates a relationship back to the originating Request.

note

This endpoint does not pre-populate required attributes. You must add required attributes to the template before posting to rest-1.v1/Data.

Examples​

Basic Story Template​

Request a basic Story template without context (no attributes pre-populated):

<Server Base URI>/rest-1.v1/New/Story

Story Template with Scope Context​

Request a Story template with a Scope as context:

<Server Base URI>/rest-1.v1/New/Story?ctx=Scope:0

Story Template with Request Context​

Request a Story template with a Request as context:

<Server Base URI>/rest-1.v1/New/Story?ctx=Request:1684

Workflow​

  1. GET a template from rest-1.v1/New with appropriate context
  2. Modify the template XML to set required and optional attributes
  3. POST the modified template to rest-1.v1/Data to create the asset
  4. Receive the created asset's XML response with OID Token