VersionOne Meta Application Programming Interface (API)
The Meta API provides a facility for retrieving information about
the VersionOne business objects. This includes getting information
about the asset types, attribute definitions, relationships and
operations. For an overview on the information model see the
API Documentation VersionOne Information Model section.
Meta allows a client of the API to discover various pieces of
information such as which attribute definitions are required, what
content is valid for an attribute, and which attributes belong to
which asset types. For example Meta will indicate that the Story
asset type has an attribute definition called Estimate which is a
Numeric attribute type and is not required.
Each asset type contains a collection of attribute definitions, a
collection of operations, and a number of useful attribute
definitions for things like sorting. Each attribute definition
describes the type of data it can contain as well as whether it is
required, read only, and multi value. Each operation contains a
reference to an attribute definition that can be used to determine
whether the specific operation can be executed on a given asset or
not.
Note that responses are always returned with a content type of
"text/xml".
There are 4 ways to retrieve information from the Meta API. You can
retrieve all of Meta in one large response, you can retrieve a
specific asset type's information, or you can retrieve information
for an attribute definition or an operation.
How to retrieve all of Meta
The following
example will retrieve the entire Meta description in a single large
XML response.
http://localhost/VersionOne/meta.v1/
<Meta href="/VersionOne/meta.v1/">
<AssetType name="State" token="State" displayname="AssetType'State" abstract="False">
<DefaultOrderBy href="/VersionOne/meta.v1/State/ID" tokenref="State.ID"/>
<DefaultDisplayBy href="/VersionOne/meta.v1/State/Code" tokenref="State.Code"/>
<AttributeDefinition name="ID" token="State.ID" displayname="AttributeDefinition'ID'State" attributetype="Relation"
isreadonly="True" isrequired="False" ismultivalue="False">
<ReciprocalRelation href="/VersionOne/meta.v1/State/ID" tokenref="State.ID"/>
<OrderByAttribute href="/VersionOne/meta.v1/State/ID" tokenref="State.ID"/>
<DisplayByAttribute href="/VersionOne/meta.v1/State/Code" tokenref="State.Code"/>
<RelatedAsset nameref="State" href="/VersionOne/meta.v1/State"/>
</AttributeDefinition>
<!-- Additional Attribute Definition Nodes -->
<!-- Additional Operation Nodes -->
</AssetType>
<!-- Addition Asset Type Nodes -->
</Meta>
The root element is called "Meta" and contains an href
attribute which indicates what URL was used to retrieve the
information. The "Meta" element will contain a number of sub
elements called "AssetType" which correspond to each of
asset types supported by the VersionOne API. In each
"AssetType" element are multiple "AttributeDefinition"
elements and multiple "Operation" elements as well as a few
other nodes that are attribute definition references which
provide suggestions on how to sort or display certain asset
types. Inside each "AttributeDefinition" node there are a
number of relevant nodes that describe the specific
attribute definition. Finally inside each "Operation" node
is a "Validator" node which is a reference to an attribute
definition that indicates whether the operation is valid for
a given asset.
How to retrieve Meta for a Story asset type
The following example will retrieve the Meta description for the
Story asset type.
http://localhost/VersionOne/meta.v1/Story
<AssetType href="/VersionOne/meta.v1/Story" name="Story" token="Story" displayname="AssetType'Story" abstract="False">
<Base nameref="PrimaryWorkitem" href="/VersionOne/meta.v1/PrimaryWorkitem"/>
<DefaultOrderBy href="/VersionOne/meta.v1/Story/Order" tokenref="Story.Order"/>
<DefaultDisplayBy href="/VersionOne/meta.v1/Story/Name" tokenref="Story.Name"/>
<AttributeDefinition name="ChangeDate" token="Story.ChangeDate" displayname="AttributeDefinition'ChangeDate'Story" attributetype="Date"
isreadonly="True" isrequired="False" ismultivalue="False">
<Base href="/VersionOne/meta.v1/BaseAsset/ChangeDate" tokenref="BaseAsset.ChangeDate"/>
<OrderByAttribute href="/VersionOne/meta.v1/Story/ChangeDate" tokenref="Story.ChangeDate"/>
</AttributeDefinition>
When asking for a specific asset type, such as the one
above, the response will be very similar to what is
displayed when asking for all of Meta. Note how the asset
type contains a "name" attribute as well as an attribute
called "abstract". The "abstract" attribute indicates that
the Story asset type is a concrete type. A Workitem asset
type on the other hand is an abstract type because other
asset types derive from it.
You'll also notice that one of the sub-nodes under the
"AssetType" element is called "Base". This is an asset type
reference node that indicates which asset type Story derives
from. In the above example the Story asset type derives from
a type called PrimaryWorkitem.
How to retrieve Meta for the Name attribute on the Story asset type
The following example will retrieve the Meta description for the
Name attribute.
http://localhost/VersionOne/meta.v1/Story/Name
<AttributeDefinition href="/VersionOne/meta.v1/Story/Name" of="/VersionOne/meta.v1/Story" name="Name" token="Story.Name"
displayname="AttributeDefinition'Name'Story" attributetype="Text" isreadonly="False" isrequired="True" ismultivalue="False">
<Base href="/VersionOne/meta.v1/BaseAsset/Name" tokenref="BaseAsset.Name"/>
<OrderByAttribute href="/VersionOne/meta.v1/Story/Name" tokenref="Story.Name"/>
</AttributeDefinition>
The root element is called "AttributeDefinition". It
contains an "of" attribute which indicates the URL of the
asset type that the attribute belongs to. It also contains a
"name" attribute and a "token" attribute. When an attribute
definition reference is used, it will contain either an
attribute called "tokenref" or "nameref" which corresponds
directly to an attribute definitions "token" and "name"
attributes respectfully.
The "displayname" attribute is an unlocalized string that
can be passed to the
Localization API to retrieve a meaningful name for the
attribute definition.
The "attributetype" attribute indicates what type of data
this attribute definition represents. See the
List of Attribute Types for more information.
Finally the node contains an "isreadonly" attribute which
indicates that the attribute is read only and cannot be
updated or set, an "isrequired" attribute which indicates
that the attribute is required to save or update an asset of
the specific asset type, and finally an "ismultivalue"
attribute which indicates that there may be multiple values
for the attribute definition.
Currently only attribute definitions of type "Relation" may
be multi-value attribute definitions.
How to retrieve Meta for the Delete operation on the Story asset
type
The following example will retrieve
the Meta description for the Delete operation.
http://localhost/VersionOne/meta.v1/Story/Delete
<Operation href="/VersionOne/meta.v1/Story/Delete" of="/VersionOne/meta.v1/Story" version="6.1.9999.30960" name="Delete">
<Validator href="/VersionOne/meta.v1/BaseAsset/IsDeletable" tokenref="BaseAsset.IsDeletable" />
</Operation>
The root element is called "Operation". It contains an "of"
attribute which indicates the URL of the asset type that the
attribute belongs to.
The operation may contain a sub element called "Validator"
which is a reference to an attribute definition. A validator
is the name of an attribute that can be asked for on an
asset to determine whether the operation is valid for the
asset.
So for example, you can query a Story asset with ID 1000 for
the IsDeletable attribute to determine whether you can call
the Delete operation on the asset.
Unlike other VersionOne API implementations, the Meta API does not
require authentication of any kind.
When a request results in an error, the response will have an HTTP
status code in the range 400-500, and detailed information about the
error will be returned in the response payload.
The response is an Error element, with an href attribute indicating
the offending requested URL. The Message element contains a textual
description of the error. Optional Exception elements may contain
technical details about the cause of the error.
Common Error Status Codes
401 Unauthorized.Â
A 401 status code indicates that the request could not be
authenticated. This may be caused by any one of these conditions:
No
credentials supplied to Basic Authentication, and no
Authorization Ticket cookie sent with the request.
An invalid username or password was supplied to Basic
Authentication.
An expired or invalid
Authorization Ticket cookie sent with the request.
The typical course of action would be to include Basic
Authorization credentials and resend the request.
404 Invalid URL.Â
A 404 status code indicates that there is no resource to
retrieve at the requested URL. This error is usually caused by an
invalid path.
405 Method Not Allowed.Â
A 405 status code indicates that the HTTP method used for
the request is not valid at the requested URL. This will be returned
for any method other than GET.
500 Internal Server Error.Â
A 500 status code indicates that an unexpected error
occurred during the processing of the request. The response payload
will contain Exception elements with specific information that will
help technical diagnose the cause of the error. This could be due
to:
An
environmental problem (e.g., the meta database is unavailable).
An unhandled exception within the VersionOne software.
Table 1. List of Attribute Types
|
Attribute Type | Data Type | Description |
|---|
|
Boolean | boolean | true or false |
|
Numeric | double | floating point number |
|
Date | datetime | date and possibly time |
|
Duration | string | a string with syntax N
UnitType where N is an integer and UnitType is Days,
Weeks, or Months |
| Text | string |
string limited to 4000 characters |
|
LongText | string | string limited by
database. Often contains html or rich text |
|
Relation | Oid | a relationship to another
asset |
| Rank | Rank | An
arbitrary object that represents one rank object
relative to another |
| AssetType |
AssetType | the name or token of an asset type |
|
Opaque | Opaque | An internal value that has
no external meaning. |
| State |
integer | A number that corresponds to an internal
asset state of an asset. |
| Password |
string | A string that represents the password for
a login. A password attribute type is write-only. It can
never be retrieved. |
| Blob | Blob |
A stream of binary data such as the content of an
Attachment asset. |
Copyright © 2007, VersionOne, LLC. All rights reserved. This document
was generated 2007-03-29Â 14:05:06.
