Asset Management REST API

1.0 Specification *DRAFT*

Contents

• Introduction
• Notations and Conventions
• Terminology
• Resource URIs and Methods
• URL Parameters
• Namespaces Used
• Media Types Used
• HTTP Headers
• Examples
  • Asset Publish
  • Asset Search
  • Asset Retrieve
• Resource Formats
• References

Introduction

Asset Management resources define the assets, artifacts, relationships and meta-data for the creation and consumption of assets in the software delivery lifecycle. The resources also represent the asset types, state, owners, and communities. This specification will focus on the definition of assets, including the asset search result.

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 formats. The capabilities of the interface definitions are driven by key integration scenarios and therefore don't represent a complete setup of operations on resources or resource types. The approach to supporting these scenarios is to delegate operations, as driven by service provider contributed user interfaces, as much as possible and not require a service provider to expose its complete data model and application logic.

Notations and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

Terminology

Asset Resource – A reusable software asset, which may be a presentation, a test case, a binary software component, and so forth.

Artifact Resource Collection - An ordered or unordered set of Artifact Resources for a given Asset Resource, typically generated as the result of performing a query or search.

Asset Resource Collection - An ordered or unordered set of Asset Resources, typically generated as the result of performing a query or search.

Search Result Collection – An order or unordered set of Asset Resources, typically generated as the result of performing a query or search.

Service Provider - an implementation of the OSLC Change Management specifications as a server. OSLC CM clients consume these services.

Summary

Resource URIs and Methods

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

For a complete list of HTTP Response Codes .

URL Parameters

Namespaces Used

The table below lists the namespace prefixes and associated namespaces used for samples and specification text. Service Providers MUST support these reserved namespace prefixes.

Media Types Used

The following table summarizes the media types used for various resource requests.

XML is the default response (to allow browsers to interact with the services) if none is specified.

• Http Header - Accept: [application/json | application/xml | application/atom+xml]
• URL suffix [.xml | .json]
• HTTP Parameter: ?oslc_assetmg.content-type={mime-type}

HTTP Headers

REST calls will return the following Vary header, which implies changes on the following Accepts.

Vary: Accept Accept-Language Accept-Charset

The following headers are looked at with regard to a REST call:

Accept

Not specifying an Accept format will return XML. YOu can specify “application/json” to receive a jSON format.

If-Modified-Since, If-None-Match

If you specify a last modified time, and an eTag, the following should be returned:

HTTP/1.x 304 Not Modified

Examples

Asset Publish

To publish an asset POST a resource representing the asset metadata to the draft asset area. This will store the metadata and return the location of draft asset. From this location artifacts can be uploaded to fill out the asset. Once your asset if ready PUT an action that you want to perform on the asset to make it available through the UI.

HTML clipboard @import url('base.css'); @import url('style.css'); @import url('colors.css'); @import url("print.css"); .style1 { color: #4571D0; text-decoration: underline; } .style2 { font-size: medium; }

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <oslc_assetmg:asset xmlns:oslc_assetmg="http://open-services.net/xmlns/assetmg/1.0/" xmlns:ras="http://www.omg.org/ras/v2.2" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">     <ras:id>         <version>1.0</version>     </ras:id>     <dc:title>GetCustomer</dc:title>     <type rel="related" href="internal/types/classif/assetTypesSchema.xmi#service_spec">         <dc:title>Service Spec</dc:title>     </type>     <community href="internal/communities/1000">         <dc:title>Service Dev Community</dc:title>     </community>     <dc:subject>get customer info</dc:subject> </oslc_assetmg:asset>

Asset Search

Asset Retrieve