RTC OSLC CM 2.0 REST API

출처 : https://jazz.net/wiki/bin/view/Main/WorkItemAPIsForOSLCCM20

This document is the next version of ResourceOrientedWorkItemAPIv2 and describes services offered by RTC 3.0.1 Work Items Service provider implementing OSLC CM 2.0 specifications. This version of service provider is much enhanced from earlier version that has more kinds of resource formats, operations etc. Most of the services and operations existed in previous version are still supported but change is only in semantics which are programmatic friendly. This document explains how Work item service provider can be consumed by referring to OSLC CM 2.0 specifications with good examples. The example snippets assume that you are authenticated to a server configured for form-based auth. These examples can be tried on a browser or by using POSTER plug in on Fire Fox.

Introduction

OSLC CM 2.0 Specification document defines a RESTful web services interface for Change Management systems, like RTC, the management of product change requests, activities, tasks and relation ships between those and related resources such as project, category, release, and plan. To support these scenarios, it defines a set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT, and DELETE, HTTP response codes, content type handling and resource formats. RTC Work Items Service provider implements these OSLC CM specifications as a server which can be consumed by clients. Some of the specifications defined by OSLC and implemented by Work Items Service Provider are listed below:

1. Resource Definitions - Defining resources like Service Provider, Work Item and other related resources like Users, Comments etc.,
2. Resource Formats and Representations - Each defined resource is represented in all the formats specified by OSLC.
   • Format type - application/rdf+xml - Resource should be in RDF/XML representation.
   • Format type - application/json - Resource should be in JSON representation.
   • Format type - application/xml - Resource should be in OSLC-defined abbreviated XML representation.
   • Format type - application/atom+xml - Resource should be in Atom Syndication Format XML representation.

1. Resource Operations - Updating or Deleting properties of resources (Work Item and other related resources) using HTTP methods
2. Creation Factories - To create a resource (Work Item and other related resources) by posting its representation.
3. Query Capabilities - To fetch resources (Work Item and other related resources) using queryable conditions, search terms, selecting properties and sorting orders.
4. Resource Paging - To fetch collection of resources (Work Item and other related resources) in pages with user defined sizes.
5. Delegated UI Dialogs - To create and select resources (Work Item and other related resources).

Following sections will explain in detail about each of the services defined above.

Discovery Mechanism

Clients that work with RTC or another implementation of the OSLC spec need a way to discover which functionality is offered by the implementation and where it is surfaced. Clients should not rely on specific URLs or perform path math on URLs. Instead, they should use the discovery chain offered by RTC. Here's an outline of the process to find the Change Management functionality:

1. The root document is exposed at https://://rootservices. In a typical RTC testbed, this is https://localhost:9443/jazz/rootservices
2. Fetch this document and extract the Change Management Catalog URL (pointed to by rdf:about) of the element oslc:ServiceProviderCatalog in
3. Fetch the document behind this URL. It contains a list of ServiceProvider elements that point to the documents which contain the actual service descriptions. In the case of RTC, there is one ServiceProvider element for each Project Area. Typically, an application would use the title of this element to allow the user to choose between the project areas.
4.  Fetch the services document pointed to by property rdf:about of element oslc:ServiceProvider. This document contains references to services and operations like Creation Factories to create new work items, Query capabilities that allows to query work items, Delegated UI dialogs to create and select work items, and CLM Filters that are pre-defined queries on work items.

Sample of a work item service provider document is illustrated in Service Provider Document.

Resource Definition

A Work Item resource is defined by the OSLC Change Request properties and RTC Work Item properties. CM Resource Definitions table has OSLC defined properties for Change Request resource.

OSLC Defined Work Item Properties

RTC Defined Work Item properties

•  Custom attributes are exposed as: rtc_cm:[attributeId]
• Contributed Link Types are exposed as: rtc_cm:[linkTypeId].[endPointId]

Resource Formats

Work Items provides representation of work item resource in all defined OSLC CM MUST resource types like RDF/XML, XML, and JSON representations. When requested for a work item in:

• application/rdf+xml Work Item resource in RDF/XML representation is responded.
• application/json Work Item resource in JSON representation is responded.
• application/xml Work Item resource in OSLC-defined abbreviated XML representation is responded.
• application/atom+xml Work Item resource in Atom Syndication Format XML representation is responded.

The usage of the OSLC CM 1.0 defined media types of application/x-oslc-cm-change-request+xml, application/x-oslc-cm-changerequest+xml, application/x-oslc-cm-change-request+json, application/x-oslc-cm-changerequest+json for work item resource is being deprecated for use in OSLC CM 2.0 based services.

Getting Representations

Work items are exposed under their Location URI. These URIs are typically obtained by a query or by using a reference from another work item. Two examples of Location URIs:

https://localhost:9443/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/262
https://localhost:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_Kk8YQFElEd6wrL4Qi7w25Q

There is an alternative URL format, called service alias format, which is mostly used for non-work item artifacts like enumeration literals, users etc. In contrast to the Location URI format, this format allows to address sub-resources like a link collection or the work item's comments. Using this format, the media type can be specified using an extension like .rdf or .xml or .json for easier testing in a browser during development time. Note that this way of specifying the media type is RTC proprietary and will work only on RTC Server. Some examples:

https://localhost:9443/jazz/oslc/workitems/821.rdf
https://localhost:9443/jazz/oslc/workitems/821.xml
https://localhost:9443/jazz/oslc/workitems/821.json
https://localhost:9443/jazz/oslc/workitems/_Kk8YQFElEd6wrL4Qi7w25Q.json
https://localhost:9443/jazz/oslc/workitems/821/rtc_cm:comments.atom

Multiple representations of a work item are available by specifying an Accept HTTP header or by specifying the required content type as an URL parameter _mediaType. These work for all URL exposed in a resource representation. Specifying an extension works only for the non-Location URI format. The first option is suitable for programmatic use, the second and third options are necessary when you have no control over the Accept header, e.g. in a browser or iFrame.

Content Type	Extension	Format
application/rdf+xml	.rdf	RDF Format as defined inOSLC Guidelines for RDF+XML representation.
application/json and text/json	.json	JSON Format as defined in OSLC Guidelines for JSON representation. The JSON formats can be requested with the additional URL parameter ?_pretty=true which will format the JSON source for better legibility. Otherwise, unnecessary whitespace is omitted.
application/xml and text/xml	.xml	XML Format as defined in OSLC Guidelines for XML representation
application/x-turtle and text/turtle	n/a	Turtle Format as defined in OSLC Guidelines for Turtle representation
application/x-jazz-compact-rendering	n/a	The Compact Rendering discovery format used to get a link title/icon and the URLs pointing to the hover presentations
text/html	.hover.html	The HTML hover representations. Additional URL parameters are currently needed: _selector=hover for the full representation _selector=smallHover for the smaller representation _context=web for slightly different link handling geared towards the Web UI (e.g. mailto links for users)
application/atom+xml	.atom	ATOM Feed format. Useful only for collections of work items, but supported for single work items, too. OSLC Guidelines for ATOM representation.
application/xhtml+xml	.xhtml	XHTML intended for exploration/debugging -- do not rely on this format

Requesting a Subset of Properties (Partial Representations)

As supported in previous version, this version of work items service provider also allows a work item resource to be represented partially with only needed properties in the response format. As per OSLC CM 2.0 specifications, OSLC core URL parameters oslc_properties=prefixA:propA, prefixB:propB and oslc_prefixes=prefixA=nsUriA, prefixB=nsUriB should be used to get the partial representation of the resource with requested properties. For syntax help on above parameters refer to Selective Property Values.

Resource Operations

Work Item Service provider as an OSLC service, implements operations like creating, updating properties of, and deleting a work item resource using HTTP POST, PUT, DELETE methods. This section explains how to update properties of a work item. Work Item properties can be categorized as follows:

• Simple property which has native values like literal, string, boolean, timestamp, integers as values.
• Reference property, a property which is a reference to another resource and can occur only once. Attributes like dcterms:contributor(owner), oslc:Discussion(comments), etc are reference properties.
• Collection property, a property which is a reference property and can occur more than once. All links such as oslc_cm:implementsRequirement, parent, children fall into this category.
• Inline property is a contained composite/collection property, whose properties will be always part of the representation of the resource containing it. oslc:comment is an inline property of oslc:Discussion

Updating Work Items

To update a Work Item resource using OSLC CM 2.0 specifications, a client should first fetch the representation of that resource as mentioned in previous section Getting Representations. Update the representation and use HTTP PUT to send the new representation to the resource's URI Steps to update a work items are as follows:

• Fetch the representation of that resource as mentioned in the section Getting Representations
• Update the representation by adding, removing or changing values
• Send the modified representation to the resource's URI using HTTP PUT

Two cases deserve special attention:
Avoid overwriting changes done by someone else: Because the update process involve first getting a work item, modifying it and then later putting back to the server there is a possibility of conflict. e.g. some other client may have updated the work item since the GET. In general, clients should not blindly overwrite the work item contents, but make sure that the changes are applied to the state that they fetched from the server. To mitigate this problem, clients should use the HTTP if-match header. This is done by including the ETag received on load in the If-Match header when PUTting the work item back to the server.
ETag information can be fetched from HTTP response headers that is written when a work item representation is requested using HTTP GET request.

HTTP/1.1 200 OK
ETag:  "_DrhL0KDHEeCbuLDfakk_jw"
Last Modified:  Mon, 27 Jun 2011 14:09:22 GMT
Cache-Control: max-age=0, must-revalidate
Expires:  Wed, 06 Jul 2011 07:52:15 GMT
Vary: Accept, Accept-Language
Content-Type:  application/rdf+xml;charset=UTF-8
Transfer-Encoding: chunked
Server:  Jetty(6.1.x)

• If the HTTP if-match header is missing, Work Item service provider will return HTTP Bad Request (400) status code to indicate the header is required.
• If the HTTP if-match header is present and it does not matches to the existing state (case where the work item was modified in the meantime), Work Item service provider behave as described in HTTP specification, returning an HTTP 412 Precondition Failed status.
• If the HTTP if-match header is present and matches, the update will be executed and on success HTTP 200 OK status is returned

Updating a Subset of Properties (Partial Updates): PUT generally has the semantics of updating the entire resource (and removing what is not included). In order to allow partial updates via the more generally supported PUT, and in order to selectively remove entire attributes from a work item, you can specify the set of properties to update via the oslc.properties parameter. If the parameter oslc.properties. contains a valid work item property on the request that is not provided in the representation content, such property will be removed. If the parameter contains a invalid work item property, then HTTP 409 Conflict is returned. OSLC Core has defined guidelines OSLC Core Guidance: Partial Update on how to do partial update a resource using HTTP PATCH request which is yet to be implemented by Work Items. Work and plan related to this is captured in the work item 141545: Implement OSLC-CM v2 partial update using PATCH.


NOTE: Clients must preserve any unknown-property-values and any other content in the work item representation when doing the update with out using oslc.properties parameter. Because, these updates will completely modify/replace the existing representation of the work item with the received representation.
Let us see how we can update (modify/delete/replace) each of these properties with examples.