AssetMgRestApiV1 < Main

This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.
TWiki>
Main Web>AssetHome>AssetMgSpecificationV1>AssetMgRestApiV1 (21 Apr 2010, TWikiAdminUser) (raw view)
---+ Asset Management REST Services API
---++ 1.0 Specification

---++ <a name="Contents"></a> Contents

%TOC%

---++ Introduction<a name="introduction" title="introduction"></a>

Asset Management resources include the asset, artifact, and relationship properties needed for the creation, retrieval, and updating of assets in the software delivery lifecycle. This version of the specification focuses on a basic definition of an asset resource and the interactions needed to satisfy the [[AssetMgScenarios][V1 usage scenarios]].

The intent of this specification is to define the set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP response codes, mime type handling and resource representations. The capabilities of the interface definitions are driven by specific integration scenarios and therefore don't represent a complete set of operations on resources or resource types. The approach is to define how service providers can interoperate with other tools without having to expose their complete data model and application logic.

Refer to the [[AssetMgDefinitions][definitions]] page for descriptions on asset management related terms used here.

---++ Notations and Conventions<a name="notationconvention" title="notationconvention"></a>

The key words &ldquo;MUST&rdquo;, &ldquo;MUST NOT&rdquo;, &ldquo;REQUIRED&rdquo;, &ldquo;SHALL&rdquo;, &ldquo;SHALL NOT&rdquo;, &ldquo;SHOULD&rdquo;, &ldquo;SHOULD NOT&rdquo;, &ldquo;RECOMMENDED&rdquo;, &ldquo;MAY&rdquo;, and &ldquo;OPTIONAL&rdquo; in this document are to be interpreted as described in <a target="_top" href="http://www.ietf.org/rfc/rfc2119.txt" style="color: blue; text-decoration: underline"> RFC2119</a>. Domain name examples use <a target="_top" href="http://tools.ietf.org/html/rfc2606" style="color: blue; text-decoration: underline"> RFC2606</a>.

---++ Summary<a name="summary" title="summary"></a>
---+++ Resource URLs and Methods<a name="resource" title="resource"></a>
 <table width="100%" cellspacing="0" cellpadding="0" id="table1" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%Resource%ENDCOLOR%</th><th valign="top" style="width: 314px">%WHITE%URL%ENDCOLOR%</th><th valign="top" style="width: 43px">%WHITE%GET%ENDCOLOR%</th><th valign="top" style="width: 47px">%WHITE%POST%ENDCOLOR%</th><th valign="top">%WHITE%PUT%ENDCOLOR%</th><th valign="top">%WHITE%DELETE%ENDCOLOR%</th><th valign="top">%WHITE%Description%ENDCOLOR%</th></tr></thead><tbody><tr><td valign="top">Asset Creation Factory </td><td valign="top" style="width: 314px">{Asset Creation URL}</td><td valign="top" style="width: 43px">N<br /></td><td valign="top" style="width: 47px">Y<br /></td><td valign="top">N</td><td valign="top">N</td><td valign="top">A URL where new Asset Resources are posted to create new Assets </td></tr><tr><td>Asset Query Resource <br /></td><td>{Asset Query URL} <br /></td><td>Y <br /></td><td>N <br /></td><td>N <br /></td><td>N <br /></td><td>A URL where you can query Asset Resources <br /></td></tr><tr><td valign="top">Asset Resource</td><td valign="top" style="width: 314px">{Asset URL}</td><td valign="top" style="width: 43px">Y</td><td valign="top" style="width: 47px">N</td><td valign="top">Y</td><td valign="top">Y</td><td valign="top">Representation of an asset resource.</td></tr><tr><td>Artifact Creation Factory <br /></td><td>{Artifact Creation URL} <br /></td><td>N <br /></td><td>Y <br /></td><td>N <br /></td><td>N <br /></td><td>A URL where new Artifact or Artifact Media Resource are posted to add new Artifacts to an Asset. <br /></td></tr><tr><td>Artifact Media Resource <br /></td><td>{Artifact Media URL} <br /></td><td>Y <br /></td><td>N <br /></td><td>Y <br /></td><td>Y <br /></td><td>Artifact media representation <br /></td></tr></tbody></table>

N - in the HTTP verb column indicates a 405 Not Supported response

For a complete list of <a target="_top" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">HTTP Response Codes</a> .

---+++ URLs for working with Assets<a name="uris" title="uris"></a>

The following table outlines the key items that are exposed in the Asset Management Service Discovery Document. Details of each of these capabilities will follow in subsequent sections. <br /><br /><table width="100%" cellspacing="0" cellpadding="0" id="table1" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%%WHITE%Purpose%ENDCOLOR%%ENDCOLOR%</th><th valign="top">%WHITE%Discovery Element%ENDCOLOR%</th><th valign="top">%WHITE%Section%ENDCOLOR%</th><th valign="top">%WHITE%%WHITE%URL%ENDCOLOR%%ENDCOLOR%</th></tr></thead><tbody><tr><td valign="top">Asset Resource Creation</td><td valign="top">&lt;assetFactory&gt;</td><td valign="top">[[#assetResourceCreation][Asset Creation]]</td><td valign="top">{Asset Creation URL}</td></tr><tr style="background-color: #fffafa"><td valign="top">Asset Resource Query</td><td valign="top">&lt;assetQuery&gt;</td><td valign="top">[[#queryResources][Get a filtered set of assets]]</td><td valign="top">{Asset Query URL}</td></tr><tr><td>Artifact Media Creation <br /></td><td>&lt;artifactContentFactory&gt; <br /></td><td>[[#addingArtifacts][Adding Artifacts to Assets]] <br /></td><td>{Artifact Media Creation URL} </td></tr></tbody></table>

---+++ URL Parameters <a name="url" title="url"></a>

The following table summarizes a set of HTTP URL parameters used for various operations. The support for these parameters varies based on which resources and what request type (GET/PUT/POST) they are used. Subsequent sections will define thie usage. <br /><br /><table width="100%" cellspacing="0" cellpadding="0" id="table2" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%Parameter%ENDCOLOR%</th><th valign="top">%WHITE%Value%ENDCOLOR%</th><th valign="top">%WHITE%Description%ENDCOLOR%</th><th valign="top">%WHITE%Sample%ENDCOLOR%</th></tr></thead><tbody><tr><td bgcolor="#ffffff" valign="top">oslc_asset.query</td><td bgcolor="#ffffff" valign="top">URL-encoded query</td><td bgcolor="#ffffff" valign="top">See [[AssetMgQuerySyntaxV1][Asset Mgmt Simple Query Syntax]]</td><td bgcolor="#ffffff" valign="top">/assets?oslc_asset.query=&lt;url-encoded-value&gt;</td></tr><tr><td bgcolor="#ffffff" valign="top">oslc_asset.properties</td><td bgcolor="#ffffff" valign="top">Comma-separated list of requested properties</td><td bgcolor="#ffffff" valign="top">Used to retrieve only desired properties</td><td bgcolor="#ffffff" valign="top">/assets?oslc_asset.properties=state,id,description,owner</td></tr><tr><td bgcolor="#ffffff" valign="top">oslc_asset.pageSize</td><td bgcolor="#ffffff" valign="top">Positive integer</td><td bgcolor="#ffffff" valign="top">Specifies the maximum number of items to return in one response</td><td bgcolor="#ffffff" valign="top">/assets?oslc_asset.pageSize=50</td></tr><tr><td>oslc_asset.name</td><td>artifact name <br /></td><td>Used to pass the name* of an artifact resource while posting an artifact media resource</td><td>/asset/artifacts?oslc_asset.name=myfile.pdf</td></tr></tbody></table>

*Servers MAY use the value of the _name_ property when creating the URI or title of the newly created Resource, for instance, by using some or all of the words in the value for the last URI segment.

---+++ Namespaces Used <a name="namespaces" title="namespaces"></a>
 <p dir="ltr">The table below lists the namespace prefixes and associated namespaces used for samples and specification text. Service Providers MUST support these reserved namespace prefixes.</p><table width="100%" cellspacing="0" cellpadding="0" id="table2" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%Prefix%ENDCOLOR%</th><th valign="top">%WHITE%Namespace%ENDCOLOR%</th><th valign="top">%WHITE%Defined%ENDCOLOR%</th></tr></thead><tbody><tr><td bgcolor="#ffffff" valign="top">oslc_asset</td><td bgcolor="#ffffff" valign="top">http://open-services.net/xmlns/asset/1.0/</td><td bgcolor="#ffffff" valign="top">

Asset Mg Resources
</td></tr><tr><td valign="top">ras</td><td valign="top">http://www.omg.org/ras/v2.2</td><td valign="top">OMG Reusable Asset Specification<br /></td></tr><tr><td bgcolor="#ffffff" valign="top">dc</td><td bgcolor="#ffffff" valign="top">http://purl.org/dc/terms/</td><td bgcolor="#ffffff" valign="top">The <a target="_top" href="http://dublincore.org/documents/dcmi-terms/">Dublin Core Metadata Terms</a> namespace</td></tr><tr><td>rdf<br /></td><td>http://www.w3.org/1999/02/22-rdf-syntax-ns#</td><td>RDF/XML<br /></td></tr><tr><td>atom<br /></td><td>http://www.w3.org/2005/Atom<br /></td><td>[[http://tools.ietf.org/html/rfc4287][RFC4287 - Atom Syndication Format<br />]]</td></tr></tbody></table>

---+++ Media Types Used<a name="media" title="media"></a>

The following table summarizes the media types used for various resource requests. See appropriate sections for specification requirements on usage.

<table cellspacing="0" cellpadding="0" id="table2" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%Media Type%ENDCOLOR%</th><th valign="top"><font color="#f0ffff">Defined</font></th><th valign="top"><font color="#f0ffff">Resource</font></th></tr></thead><tbody><tr><td valign="top">application/xml </td><td valign="top"><a target="_top" href="http://www.w3.org/TR/xml/">W3C Extensible Markup Language (XML) 1..0</a></td><td valign="top">General XML format request/response </td></tr><tr><td>application/json </td><td>&lt;a target="_top" href="http://tools.ietf.org/html/rfc4627"&gt;RFC4627 - The application/json Media Type for JavaScript Object Notation (JSON)&lt;/a&gt;<br /></td><td>General JSON format request/response <br /></td></tr><tr><td>application/atom+xml </td><td><a target="_top" href="http://tools.ietf.org/html/rfc4287">RFC4287 - Atom Syndication Format</a> , <a target="_top" href="http://tools.ietf.org/html/rfc5005">RFC5005 - Feed Paging and Archiving</a></td><td>Asset Query Resource</td></tr><tr><td>application/zip <br /></td><td>Asset manifest and artifact medias in a single zip fiie. <br /></td><td>Asset Resource Zipped <br /></td></tr><tr><td>application/ras<br /></td><td>Asset Resource representation based on the [[http://www.omg.org/technology/documents/formal/ras.htm][reuable asset specification]] (RAS) format. A RAS format is a a zip with a collection of Artifact Media Resources, and a RAS manifest. <br /></td><td>Asset Resource<br /></td></tr></tbody></table>

Service Implementers MUST support RDF/XML formats. Service Implementers MAY support JSON formats.

---+++ Requesting Formats <a name="requestingFormat" title="requestingFormat"></a>

There will be a single supported method for a client to designate it's required response format, using the HTTP request header of Accept

If only Accept header is supplied and has more than one {mime-type}, then the server will determine the {mime-type} will be used for the response content type.<br />If none are provided then a default is used, which is application/xml unless defined otherwise.

If the requested {mime-type} is unknown, a HTTP response code of 415 Unsupported Media Type will be returned.<br />Each of the operation on a given URI may support a different default {mime-type}.

Service implementors MAY specify alternate ways (i.e. url extension or url accept parameter) to specify a requesting format.

---+++ Selective Properties <a name="selectiveProperties" title="selectiveProperties"></a>

A client MAY request a restricted number of resource properties as well as properties from a referenced resource. In order to support this behavior a service provider MUST support the oslc_asset.properties parameter on HTTP GET requests on individual resource requests as well as for requests on Asset Query Resources. If the oslc_asset.properties parameter is omitted on the request, then all resource properties MUST be provided in the response.

If properties listed in the oslc_asset.properties do not exist for the resource, a HTTP response status of 409 Conflict MUST be used.

If the resource does not exist at the request URL, a HTTP response status of 404 Not Found MUST be used.

This property may also be used to perform [[#partialUpdate][partial updates]].

*Parameter:* oslc_asset.properties

*Syntax:*

*BNF*
<verbatim>
properties  ::= property ("," property)*
property    ::= identifier | nested_prop | wildcard
nested_prop ::= property "{" properties "}"
identifier  ::= word (":" word)?
word        ::= /any sequence of letters and numbers, starting with a letter/
wildcard    ::= "*"
</verbatim>

*Sample:*

Request the Asset resource at {Asset Resource URI} and only the properties of title (asset name) and version.

*Request:*
<pre>{Asset Resource URI}?oslc_asset.properties=dc:title,ras:id{version}</pre>

*Response:*
<verbatim>
<oslc_asset:asset>
   <dc:title>GetCustomer</dc:title>        
   <ras:id>               
      <version>1.2</version>    
   </ras:id>
</oslc_asset:asset>
</verbatim>

---+++ Artifact Media Resources <a name="resourcesVsMediaResources" title="resourcesVsMediaResources"></a>

An Asset's Artifacts have a Media Resource representing the actual content of the Artifact. This relationship between an Asset's Artifacts and associated Media Resources is defined in the same manner as the [[http://tools.ietf.org/html/rfc5023#section-9.6][Media Resource and Media Link Entries]] for the Atom Publishing Protocol.

A client can POST Media Resources (content) to the {Artifact Media Creation URL} which is a property of the Asset. When POSTed, the service provider creates a new Media Resource and adds an associated Artifact property to the Asset.

The Artifact property has properties which include the URL to the (potentially binary) Media Resource. The Property thus makes the description for that Media Resource separately available for retrieval and alteration.

Successful responses to creation requests must return a status code of 201, and a Location Header indicating the URL of the Media Resource. The new Artifact property must have an olsc_asset:content element with a "rdf:resource" attribute. The value of the "rdf:resource" attribute is an URL for the newly created Media Resource.

Upon successful creation of a Resource, a server must populate mandatory elements with values derived from the POSTed entity or from any other source. A server may not allow a client to modify server-selected values (such as creation time, size, mime type).

---++ Resource Creation <a name="resourceCreation" title="resourceCreation"></a>

---+++ Asset Creation <a name="assetResourceCreation" title="assetResourceCreation"></a>

POST {Asset Creation URL}

Creates a new asset based using the content body from the request.

A service provider MUST support at least the following HTTP response status codes: <table width="100%" cellspacing="0" cellpadding="0" id="table2" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%Code%ENDCOLOR%</th><th valign="top">%WHITE%Content%ENDCOLOR%</th><th valign="top">%WHITE%Description%ENDCOLOR%</th></tr></thead><tbody><tr><td bgcolor="#ffffff" valign="top">201 OK<br /></td><td bgcolor="#ffffff" valign="top">HTTP-Header&gt; Location {New Asset UR} </td><td bgcolor="#ffffff" valign="top">A new asset resource has been created at the URI returned.<br /></td></tr><tr><td valign="top">403 Forbidden </td><td valign="top">Error Message<br /></td><td valign="top">Server rejects request. User not authorized to create the resource. </td></tr></tbody></table>

[[#publishAsset][Example]]

---+++ Adding Artifacts to an Asset <a name="addingArtifacts" title="artifactArtifacts"></a>

POST {Artifact Media Creation URL}

Creates a new artifact based using the content body from the request. You name use the oslc_asset.name parameter to supply an artifact name to the service.

A service provider MUST support at least the following HTTP response status codes:

<table width="100%" cellspacing="0" cellpadding="0" id="table2" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%Code%ENDCOLOR%</th><th valign="top">%WHITE%Content%ENDCOLOR%</th><th valign="top">%WHITE%Description%ENDCOLOR%</th></tr></thead><tbody><tr><td bgcolor="#ffffff" valign="top">201 OK<br /></td><td bgcolor="#ffffff" valign="top">HTTP-Header&gt; Location {New Artifact Media URI} and the Artrifact Resource per Accept Header.<br /></td><td bgcolor="#ffffff" valign="top">A new artifact resource has been created at the URI returned.<br /></td></tr><tr><td valign="top">403 Forbidden </td><td valign="top">Error Message<br /></td><td valign="top">Server rejects request. User not authorized to create the resource. </td></tr></tbody></table>

---++ Get Resources<a name="get" title="get"></a>
---+++ Get an Asset <a name="getAnAssetResource" title="getAnAssetResource"></a>
 <br />GET {Asset Resource URI}

Returns the asset resource from the URI given.

The service provider MUST Accept these media types for the response content body:
   * application/xml
   * application/zip

The service provider MAY Accept these media types for the response content body:
   * application/json
   * application/ras

A server provider MAY return an <a target="_top" href="http://tools.ietf.org/html/rfc2616#section-14.19"> ETag HTTP header</a> in the response that can be included in HTTP PUT requests for concurrent modification validation.

A service provider MUST support at least the following HTTP response status codes:

<table width="100%" cellspacing="0" cellpadding="0" id="table2" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%Code%ENDCOLOR%</th><th valign="top">%WHITE%Content%ENDCOLOR%</th><th valign="top">%WHITE%Description%ENDCOLOR%</th></tr></thead><tbody><tr><td bgcolor="#ffffff" valign="top">200 OK<br /></td><td bgcolor="#ffffff" valign="top">Asset Resource per Accept Header</td><td bgcolor="#ffffff" valign="top">A representation of the asset resource.<br /></td></tr><tr><td valign="top">403 Forbidden </td><td valign="top">Error Message<br /></td><td valign="top">Server rejects request. User not authorized to create the resource </td></tr><tr><td bgcolor="#ffffff" valign="top">404 Not Found</td><td bgcolor="#ffffff" valign="top">Error Message</td><td bgcolor="#ffffff" valign="top">Asset does not exist on the server<br /></td></tr></tbody></table>

[[#downloadLog4jAsset][Example]]

---+++ Get an Artifact Media Resource <a name="getAnArtifactMediaResource" title="getAnArtifactMediaResource"></a>

GET {Artifact Media Resource URI}

Returns the artifact media resource from the URI given.

A server provider MAY return an <a target="_top" href="http://tools.ietf.org/html/rfc2616#section-14.19"> ETag HTTP header</a> in the response that can be included in HTTP PUT requests for concurrent modification validation.

A service provider MUST support at least the following HTTP response status codes:

<table width="100%" cellspacing="0" cellpadding="0" id="table2" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%Code%ENDCOLOR%</th><th valign="top">%WHITE%Content%ENDCOLOR%</th><th valign="top">%WHITE%Description%ENDCOLOR%</th></tr></thead><tbody><tr><td>200 OK<br /></td><td>Artifact Media Resource<br /></td><td>A content of the artifact resource.<br /></td></tr><tr><td valign="top">403 Forbidden </td><td valign="top">Error Message<br /></td><td valign="top">Server rejects the request. User not authorized to view the resource. </td></tr><tr><td bgcolor="#ffffff" valign="top">404 Not Found</td><td bgcolor="#ffffff" valign="top">Error Message</td><td bgcolor="#ffffff" valign="top">Server rejects the request. Artifact does not exist on the server. </td></tr></tbody></table>

---++ Asset Query Resources<a name="queryResources" title="Query Resources"></a>

GET {Asset Query URL}

Returns a collection of assets. The service MUST support application/atom+xml and MAY support application/json for the response content body.

When returning application/json format, the service provider MUST provide the properties of each resource within the atom:content element of the atom:entry element.

The number of entries in the collection response are driven by HTTP query parameters oslc_asset.query. If this parameter is omitted, the server MAY respond with:
   * a page of results
   * all results
<table width="100%" cellspacing="0" cellpadding="0" id="table2" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%Code%ENDCOLOR%</th><th valign="top">%WHITE%Content%ENDCOLOR%</th><th valign="top">%WHITE%Description%ENDCOLOR%</th></tr></thead><tbody><tr><td bgcolor="#ffffff" valign="top">200 OK<br /></td><td bgcolor="#ffffff" valign="top">Collection of assets in format per Accept header</td><td bgcolor="#ffffff" valign="top">A collection of assets with summary information and references to external change requests. </td></tr><tr><td bgcolor="#ffffff" valign="top">406 Not Acceptable </td><td bgcolor="#ffffff" valign="top">Error Message</td><td bgcolor="#ffffff" valign="top">Server can not fulfill the request due to it's Accept headers </td></tr></tbody></table>

[[#queryForLog4j][Example]]

---+++ *Query Syntax* <a name="querySyntax" title="querySyntax"></a>

A filtered set of Assets can be retrieved using a HTTP GET-based method where query terms are URL-encoded.

Service providers MUST support the query syntax supported in the [[AssetMgQuerySyntaxV1][Asset Management Query Syntax]] specification.

---+++ Pagination <a name="pagination"></a>

Asset Query representations SHOULD be limited in size by the request parameter oslc_asset.pageSize.

Subsequent pages MUST be able to be requested using pagination elements in the Asset Query Resource response content.

For application/atom+xml representations, these additional link rels MUST be supported as defined in <a target="_top" href="http://tools.ietf.org/html/rfc5005">RFC5005 - Atom Feed Paging and Archiving</a>:
   * next - A URI that refers to the immediately following document in a series of documents.
   * previous - A URI that refers to the immediately preceding document in a series of documents.

For exmaple:
<verbatim><atom:feed xml:base="http://localhost:8080/am/" oslc_asset:totalCount="853">
    <atom:id>Asset Manager 1.2 [http://localhost:8080/am/oslc/search] - 7/18/09 1:18 PM</atom:id>
    <link rel="next" href="oslc/search?oslc_query=title=&quot;Server&quot;?oslc_asset.oslc_startIndex=201&oslc_asset.oslc_pageSize=200"/>
    <atom:link type="application/atom+xml" rel="self" href="oslc/search?oslc_query=title=&quot;Server&quot;&oslc_asset.oslc_pageSize=200"/>
    <atom:title>Asset Query Result [title="Server"]</atom:title>
    <atom:updated>2009-07-18T12:44:25.640-04:00</atom:updated>
    <atom:entry xml:base="http://localhost:8080/am/">
...
</verbatim>

For application/atom+xml representations these is additional elements MAY be supported:
   * oslc_asset:totalCount - A positive integer that represents the total number of resources that are a result of the request.
As an example, a query request that would result in 200 entries and is limited by a oslc_asset:pageSize=20, then oslc_asset:totalCount=200.

For application/json Resource Collections the additional attributes defined in [[CmJsonFormatV1][JSON format]] MUST be supported.

---++ Update a resource <a name="updateResources" title="updateResources"></a>

---+++ Update an asset <a name="updateAsset" title="updateAsset"></a>

PUT {Asset Resource URI}

Update the referenced asset resource with the request's body. The service MUST support =application/xml= and MAY support =application/json= for the request's content body.

A service provider MUST support at least the following HTTP response status codes:

<table width="100%" cellspacing="0" cellpadding="0" id="table2" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%Code%ENDCOLOR%</th><th valign="top">%WHITE%Content%ENDCOLOR%</th><th valign="top">%WHITE%Description%ENDCOLOR%</th></tr></thead><tbody><tr><td bgcolor="#ffffff" valign="top">200 OK<br /></td><td bgcolor="#ffffff" valign="top">Asset Resource per Accept Header.<br /></td><td bgcolor="#ffffff" valign="top">Once the asset is updated with the supplied changes, the resulting asset representation is returned.<br /></td></tr><tr><td>400 Bad Request <br /></td><td>Error Message <br /></td><td>Server rejects the request. The uploaded content was malformed. <br /></td></tr><tr><td valign="top">403 Forbidden </td><td valign="top">Error Message<br /></td><td valign="top">Server rejects the request. User not authorized to update the resource. </td></tr><tr><td bgcolor="#ffffff" valign="top">404 Not Found</td><td bgcolor="#ffffff" valign="top">Error Message</td><td bgcolor="#ffffff" valign="top">Server rejects the request. Asset does not exist on the server. </td></tr><tr><td>409 Conflict <br /></td><td>Error Message <br /></td><td>Server rejects the request. The asset has been modified on the server. <br /></td></tr><tr><td>415 Unsupported Media Type <br /></td><td>Error Message <br /></td><td>Server rejects the request. The media type requested by the accept header is not supported by the server. <br /></td></tr></tbody></table>

---+++ Partial update<a name="partialUpdate" title="partialUpdate"></a>

The resource's request representation can be a subset of the complete resource. The URL in the PUT request must provide the list of properties to be updated (see the [[#selectiveProperties][Selective Properties]] section for the property details).

An abbreviated example where only the =dc:title= and =dc:subject= properties are updated could be:
<verbatim>PUT {Asset Resource URI}?oslc_asset.properties=dc:title,dc:subject
Content:
<oslc_asset:Asset>
  <dc:title>Myco Web Services</dc:title>
  <dc:subject>Web services for the Myco web site.</dc:subject>
</oslc_asset:Asset> 
</verbatim>

If the parameter =oslc_cm.properties= contains a valid resource property on the request that is not provided in the content, the server must set the resource's property to a null or empty value.

If the parameter =oslc_cm.properties= contains an invalid resource property, then a =400 Bad Request= must be returned.

---+++ Delete a resource <a name="deleteResources" title="deleteResources"></a>

DELETE ={Resource URI}=

Delete a resource represented by the given URL. Further GET requests on this resource SHOULD result in a "410 Gone" or a "404 Not Found" response.

A service provider MUST support at least the following HTTP response status codes:

<table width="100%" cellspacing="0" cellpadding="0" id="table2" border="1"><thead><tr style="background-color: #000099"><th valign="top">%WHITE%Code%ENDCOLOR%</th><th valign="top">%WHITE%Content%ENDCOLOR%</th><th valign="top">%WHITE%Description%ENDCOLOR%</th></tr></thead><tbody><tr><td bgcolor="#ffffff" valign="top">200 OK<br /></td><td bgcolor="#ffffff" valign="top">none<br /></td><td bgcolor="#ffffff" valign="top">The service has marked the resource as deleted or physically deleted the resource.</td></tr><tr><td valign="top">403 Forbidden </td><td valign="top">Error Message<br /></td><td valign="top">Server rejects the request. User not authorized to delete the resource. </td></tr><tr><td bgcolor="#ffffff" valign="top">404 Not Found</td><td bgcolor="#ffffff" valign="top">Error Message</td><td bgcolor="#ffffff" valign="top">Server rejects the request. Resource does not exist on the server. </td></tr></tbody></table>

---++ Examples <a name="examples" title="examples"></a>

In this scenario a build system will search the asset management system looking for an approved logging asset to include in the build. Upon finding the approved logging asset, the build system retrieves the logging asset and performs the build. The build system publishes the built component (.ear) to the asset management system. This scenario is described further in the [[AssetMgScenarios][Asset Management Scenarios For v1 REST Spec]].

---+++ Query Example<a name="queryExample" title="queryExample"></a>
 *Build system queries Asset Management system for assets to include in the build* <a name="scenario_buildasset_search" title="scenario_buildasset_search"></a>

In this example a build process will search for the latest version of an asset to include in a build. It will query for assets of a given name.
   * The build script specifies the asset to be included in the build
   * The build system queries the asset repository for the latest approved version of the specific assets.

The build system queries using the asset's name and the asset's state. For our purposes here the "Approved" asset are those which can be included in a build.

From the [[AssetMgScenarios#searchbuildassets][Build System Query Use Case Scenario]]

---++++ Get the service definition <a name="getServiceDefinition" title="getServiceDefinition"></a>
 <ol><li>*Request:* GET https://server:9443/am/oslc/assets/services<br />Accept: application/xml<br /><br /> *Response:* <br />Status Code: 200 (OK)<br />Content-Type: application/xml<br />Body: <br />
<verbatim>
<?xml version="1.0" encoding="UTF-8"?>
<oslc_asset:ServiceDescriptor rdf:about="https://server:9443/am/oslc/assets/services">
	<dc:title>Asset Management Services</dc:title>
	<dc:description>Asset Manager OSLC Service Description</dc:description>
	<dc:contributor>
		<dc:title>Asset Manager</dc:title>
		<dc:identifier>com.myco.am.assets</dc:identifier>
		<oslc_asset:icon> https://am/images/AssetManager.ico
		</oslc_asset:icon>
	</dc:contributor>

	<!-- Services -->
	<oslc_asset:assets oslc_asset:version="1.0">
		<oslc_asset:home rdf:about="https://server:9443/am/home.faces">
			<dc:title>Assets Home</dc:title>
		</oslc_asset:home>

		<!-- Create asset location -->
		<oslc_asset:factory rdf:about="https://server:9443/am/oslc/assets">
			<dc:title>Default location for creation of assets</dc:title>
		</oslc_asset:factory>

		<!-- Asset Simple Query -->
		<oslc_asset:simpleQuery rdf:about="https://server:9443/am/oslc/simpleQuery">
			<dc:title>Assets queries</dc:title>
		</oslc_asset:simpleQuery>
	</oslc_asset:assets>
</oslc_asset:ServiceDescriptor>
</verbatim></li><li>

---++++ Query for the latest approved Apache Logging Services Project asset <a name="queryForLog4j" title="queryForLog4j"></a>
 *Request:* GET https://server:9443/am/oslc/simpleQuery?oslc_asset.query=oslc_asset:state="Approved" and dc:title="Apache Logging Services Project"&oslc_asset.properties=ras:id,dc:title<br />Accept: application/atom+xml<br /><br /><strong>Response:<br /></strong>Status Code: 200 (OK)<br />Content-Type: application/atom+xml<br />
<verbatim>
<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xml:base="http://localhost:8080/am/">
	<atom:id>Asset Manager 7.2 [http://localhost:8080/am/oslc/search]
		- 7/18/09 1:18 PM</atom:id>
	<atom:link type="application/atom+xml" rel="self"
		href="oslc_asset.query=oslc_asset:state=&quot;Approved&quot; and dc:title=&quot;Apache Logging Services Project&quot;&oslc_asset.properties=ras:id,dc:title" />
	<atom:title>Asset Query Result [oslc_asset:state=&quot;Approved&quot; and dc:title=&quot;Apache Logging Services Project&quot;"]</atom:title>
    <atom:updated>2009-07-18T12:44:25.640-04:00</atom:updated>
    <atom:entry xml:base="http://localhost:8080/am/">
        <atom:id>{1082CDD3-1E40-5648-E7DC-5137CC841AA5}/1.2</atom:id>
        <atom:link type="text/html" rel="alternate" href="assetDetail/generalDetails.faces?guid=%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D&v1.2"></atom:link>
        <atom:link type="text/xml" rel="alternate" href="oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.2"></atom:link>
        <atom:summary>Apache Logging Services Project is an open source project based on the work of many authors.  It allows the developer to control which log statement are output with arbitrary granularity.</atom:summary>
        <atom:title>Apache Logging Services Project [1.2]</atom:title>
        <atom:updated>2009-07-18T12:31:11.265-04:00</atom:updated>
        <atom:content type="application/xml">
            <asset rdf:resource="oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.2">
                <ras:id>
                    <ras:GUID>{882B4FD7-3C72-4DB0-8097-66866E7D45F6}</ras:GUID>
                    <ras:version>1.2</ras:version>
                </ras:id>
                <dc:title>Apache Logging Services Project</dc:title>
            </asset>
        </atom:content>
    </atom:entry>
    <atom:entry xml:base="http://localhost:8080/am/">
        <atom:id>{1082CDD3-1E40-5648-E7DC-5137CC841AA5}/1.0.4</atom:id>
        <atom:link type="text/html" rel="alternate" href="assetDetail/generalDetails.faces?guid=%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D&v1.0.4"></atom:link>
        <atom:link type="text/xml" rel="alternate" href="oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.0.4"></atom:link>
        <atom:summary>Apache Logging Services Project is an open source project based on the work of many authors.  It allows the developer to control which log statement are output with arbitrary granularity.</atom:summary>
        <atom:title>Apache Logging Services Project [1.0.4]</atom:title>
        <atom:updated>2005-11-21T12:31:23.235-04:00</atom:updated>
        <atom:content type="application/xml">
            <asset rdf:resource="oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.0.4">
                <ras:id>
                    <ras:GUID>{882B4FD7-3C72-4DB0-8097-66866E7D45F6}</ras:GUID>
                    <ras:version>1.0.4</ras:version>
                </ras:id>
                <dc:title>Apache Logging Services Project</dc:title>
            </asset>
        </atom:content>
    </atom:entry>
</atom:feed> 
</verbatim></li></ol>

---+++ Retrieve Example <a name="retrieveExample" title="retrieveExample"></a>
 *Build system retrieves asset from Asset Management system to include in the build* <a name="scenario_buildasset_search" title="scenario_buildasset_search"></a>

The build system has identified the asset to include in the build. In this scenario the build system retrieves the specific asset from the Asset Management system to be included in the build.
   * The build system downloads the full description of the latest version (1.2) of the Apache Logging Services Project asset. The build logs information about this asset (name, URL, owners, and list of artifact) in to the build results log.
   * The build notices that this asset has only a single artifact (log4j.jar) so the build downloads the artifact media resource directlly and places this jar in the compliation path for the build.
From the [[AssetMgScenarios#retrievebuildassets][Build System Retrieve Use Case Scenario]] <ol><li>

---++++ Download the Apache Logging Services Project asset resource <a name="downloadLog4jAsset" title="downloadLog4jAsset"></a>
 *Request:* GET https://server:9443/am/oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.2<br />Accept: application/xml<br /><br /><strong>Response:<br /></strong>Status Code: 200 (OK)<br />Content-Type: application/xml<br />Body: 
<verbatim>
<oslc_asset:asset rdf:about="https://server:9443/am/oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.2">
    <ras:id>
        <ras:GUID>{882B4FD7-3C72-4DB0-8097-66866E7D45F6}</ras:GUID>
        <ras:version>1.2</ras:version>
    </ras:id>
    <dc:title>Apache Logging Services Project</dc:title>
    <dc:subject>Apache Logging Services Project is an open source project based on the work of many authors.  It allows the developer to control which log statement are output with arbitrary granularity.</dc:subject>
    <dc:type>Software</dc:type>
    <oslc_asset:state>Approved</oslc_asset:state>
    <dc:contributor>bobsmith@myco.com</dc:contributor>
    <oslc_asset:artifactContentFactory rdf:about="https://server:9443/am/oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.2/artifacts"/>
    <oslc_asset:artifact>
        <dc:title>log4j.jar</dc:title>
        <oslc_asset:size>123412</oslc_asset:size>
        <oslc_asset:mimeType>application/java-archive</oslc_asset:mimeType>
        <oslc_asset:content rdf:resource="https://server:9443/am/oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.2/artifactContents/log4j.jar"/>     
    </oslc_asset:artifact> 
</oslc_asset:asset>
</verbatim></li><li>

---++++ Download the Apache Logging Services Project's log4j.jar artifact media resource <a name="downloadLog4jArtifact" title="downloadLog4jArtifact"></a>
 <br /> *Request:* GET https://server:9443/am/oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.2/artifactContents/log4j.jar<br /><br /> *Response:* <br />Status Code: 200 (OK)<br />Content-Type: application/java-archive<br />Body: &lt;JAR File&gt; </li></ol>

---+++ Publish Example <a name="publishExample" title="publishExample"></a>

Build wants to create an asset with the EAR file it has built and the an HTML document that includes a build summary. It will relate the new asset to an asset containing the log4j library used in the build.

From the [[AssetMgScenarios#publishbuildassets][Build System Publish Use Case Scenario]]
<ol><li>

---++++ POST to the asset factory to create a new asset<a name="publishAsset" title="publishAsset"></a>
 <strong><br />Request:</strong> <br />POST https://server:9443/am/oslc/assets<br />Accept: application/xml<br />Body:<br />
<verbatim>
<oslc_asset:asset>
     <ras:id>
        <ras:version>1.0.20091011</ras:version>
    </ras:id>
    <dc:title>Myco Services Application</dc:title>
    <dc:subject>My Company's REST Services Application</dc:subject>
    <dc:type>Application</dc:type>
    <oslc_asset:relation rdf:resource="https://server:9443/am/oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.2">
        <dc:title>Logging Service</dc:title>
        <dc:type>Dependency</dc:type>
    </oslc_asset:relation>  
</oslc_asset:asset>
</verbatim></li><li> *Response:* <br />Status Code: 201 (Created)<br />Location: https://server:9443/am/oslc/assets/%7B1082CDD3-1E40-5648-E7DC-5137CC841AA5%7D/1.0<br />Content-Type: application/xml<br />Body:<br />
<verbatim>
<oslc_asset:asset rdf:about="https://server:9443/am/oslc/assets/%7B1082CDD3-1E40-5648-E7DC-5137CC841AA5%7D/1.0">
    <ras:id>
        <ras:GUID>{1082CDD3-1E40-5648-E7DC-5137CC841AA5}</ras:GUID>
        <ras:version>1.0.20091011</ras:version>
    </ras:id>
    <dc:title>Myco Services Application</dc:title>
    <dc:subject>My Company's REST Services Application</dc:subject>
    <dc:type>Application</dc:type>
    <oslc_asset:state>Approved</oslc_asset:state>
    <dc:contributor>bobsmith@myco.com</dc:contributor>
    <oslc_asset:artifactContentFactory rdf:about="https://server:9443/am/oslc/assets/%7B1082CDD3-1E40-5648-E7DC-5137CC841AA5%7D/1.0/artifacts"/>
    <oslc_asset:relation rdf:resource="https://server:9443/am/oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.2">
        <dc:title>Logging Service</dc:title>        
        <dc:type>Dependency</dc:type>
    </oslc_asset:relation>
</oslc_asset:asset>
</verbatim></li><li>

---++++ Post the built EAR to the asset's artifact content factory URL <a name="publishEar" title="publishEar"></a>
 <strong><br />Request:</strong> POST https://server:9443/am/oslc/assets/%7B1082CDD3-1E40-5648-E7DC-5137CC841AA5%7D/1.0/artifacts<br />oslc_asset.name: services.ear<br />Body: &lt;EAR file&gt;<br /><br /> *Response:* <br />Status Code: 201 (created)<br />Location: https://server:9443/am/oslc/assets/%7B1082CDD3-1E40-5648-E7DC-5137CC841AA5%7D/1.0/artifactContents/services.ear</li><li>

---++++ Update the created artifact's subject<a name="updateEAR" title="updateEAR"></a>
 <br />The system performs a partial update on the asset overriding the list of artifacts in the asset. We add a new artifact (with remote content) that is the build summary <strong><br />Request:</strong> <br />PUT https://server:9443/am/oslc/assets/%7B1082CDD3-1E40-5648-E7DC-5137CC841AA5%7D/1.0?oslc_asset.properties=artifact<br />Accept: application/xml<br />Content-Type: application/xml<br />Body:<br />
<verbatim>
<oslc_asset:asset rdf:about="https://server:9443/am/oslc/assets/%7B1082CDD3-1E40-5648-E7DC-5137CC841AA5%7D/1.0">
   <oslc_asset:artifact>
      <dc:title>services.ear</dc:title>
      <oslc_asset:content rdf:resource="https://server:9443/am/oslc/assets/%7B1082CDD3-1E40-5648-E7DC-5137CC841AA5%7D/1.0/artifactContents/services.ear"/>
      <dc:subject>MyCo's employee web services Java Enterprise Application [2009-10-11T12:10:16.593-04:00]</dc:subject>
   </oslc_asset:artifact>
   <oslc_asset:artifact>
      <dc:title>buildSummary.html</dc:title>
      <oslc_asset:content rdf:resource="https://buildServer/fullcontrol/index.php?mod=jobs&action=edit&bf_id=965518"/>
      <dc:subject>Myco Services[2009-10-11T12:10:16.593-04:00] Build Results</dc:subject>
   </oslc_asset:artifact>
</oslc_asset:asset>
</verbatim><br /> *Response:* <br />Status Code: 200 (OK)<br />Content-Type: application/xml<br />Body: <br /><verbatim><oslc_asset:asset rdf:about="https://server:9443/am/oslc/assets/%7B1082CDD3-1E40-5648-E7DC-5137CC841AA5%7D/1.0">
    <ras:id>
        <ras:GUID>{1082CDD3-1E40-5648-E7DC-5137CC841AA5}</ras:GUID>
        <ras:version>1.0.20091011</ras:version>
    </ras:id>
    <dc:title>Myco Services Application</dc:title>
    <dc:subject>My Company's REST Services Application</dc:subject>
    <dc:type>Application</dc:type>
    <oslc_asset:state>Approved</oslc_asset:state>
    <dc:contributor>bobsmith@myco.com</dc:contributor>
    <oslc_asset:artifactContentFactory rdf:about="https://server:9443/am/oslc/assets/%7B1082CDD3-1E40-5648-E7DC-5137CC841AA5%7D/1.0/artifacts"/>
    <oslc_asset:artifact>
        <dc:title>services.ear</dc:title>
        <oslc_asset:size>6439267</oslc_asset:size>
        <oslc_asset:content rdf:resource="https://server:9443/am/oslc/assets/%7B1082CDD3-1E40-5648-E7DC-5137CC841AA5%7D/1.0/artifactContents/services.ear"/>
        <oslc_asset:mimeType>application/java-archive</oslc_asset:mimeType>
        <dc:subject>MyCo's employee web services Java Enterprise Application [2009-10-11T12:10:16.593-04:00]</dc:subject>
        <oslc_asset:lastModified>2009-10-11T12:10:16.593-04:00</oslc_asset:lastModified>   
    </oslc_asset:artifact>
    <oslc_asset:artifact>
        <dc:title>buildSummary.html</dc:title>
        <oslc_asset:content rdf:resource="https://buildServer/fullcontrol/index.php?mod=jobs&action=edit&bf_id=965518"/>
        <dc:subject>Myco Services[2009-10-11T12:10:16.593-04:00] Build Results</dc:subject>
    </oslc_asset:artifact>
    <oslc_asset:relation rdf:resource="https://server:9443/am/oslc/assets/%7B882B4FD7-3C72-4DB0-8097-66866E7D45F6%7D/1.2">
        <dc:title>Appache Logging Service</dc:title>
        <dc:type>Dependency</dc:type>
    </oslc_asset:relation>
</oslc_asset:asset>
</verbatim></li><li>

---++ Resource Formats <a name="resourceFormats" title="resourceFormats"></a>
   * [[AssetMgResourceDefinitionsV1][OSLC Asset resource definition specification]]
   * [[ArtifactResourceDefinitionsV1][OSLC Artifact resource definition specification]]
   * [[AssetMgServiceDescriptionV1][OSLC Asset Management service description document]]

---++ References <a name="references" title="references"></a>
   * [[http://www.ietf.org/rfc/rfc2616.txt][RFC2616 HTTP]]
   * [[AssetMgScenarios][OSLC Asset Management Use Cases & Scenarios]]
</li></ol>
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who
gif	assetUploadExample.gif	manage	18.8 K	20 Oct 2009 - 19:18	KevinBauer
gif	rest_publish_asset_scenario.gif	manage	24.6 K	05 Oct 2009 - 14:53	GrantLarsen
gif	rest_retrieve_asset_scenario.gif	manage	35.2 K	07 Oct 2009 - 15:36	GrantLarsen
Topic revision: r89 - 21 Apr 2010 - 17:44:51 - TWikiAdminUser
Main
Webs
Main
Sandbox
TWiki
Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback