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.

Change Management REST API

1.0 SPECIFICATION

Introduction

Change Management resources define the change requests, activities and tasks of the software delivery lifecycle. They represent individual change requests, activities and tasks, along with their relationships to other shared resource types such as project, category, release and plan. 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 resource formats and operations may not match exactly the native models supported by change management service providers but are intended to be compatible with them. 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.

Notation 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

Change Request Resource - A request for change to an application or product. Typically a product request for enhancement or a report for a resolution of a product defect.

Resource Collection - An ordered or unordered set of 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

Resource URI GET POST PUT DELETE Description
Collection of Change Requests {CR Collection URI} Y * N N A collection of change requests
Change Request {CR URI} Y N Y Y An identifiable change request, by a permanant URI

* - the collection MAY support creation on its URI, see Create a new Change Request

N - in the HTTP verb column indicates that a Service Provider MUST return a 405 Not Supported response

For a complete list of HTTP Response Codes

URIs for working with Change Requests

The following table outlines the key items that are exposed in the Change Management Service Discovery Document. Details of each of these capabilities will follow in subsequent sections.

Purpose Discovery Element URL* Section Support
Resource Creation <factory> {Resource Creation URL} Create a new Change Request REQUIRED
Resource Query <simpleQuery> {Simple Query URL} Get a Collection of Change Requests REQUIRED
Resource Selection UI <selectionDialog> {Selection Dialog URL} Resource Selection REQUIRED
Resource Creation UI <creationDialog> {Creation Dialog URL} Resource Creation REQUIRED

* URL column represents notational convention used later in this specification

URL Parameters

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.

Parameter Value Description Sample
oslc_cm.query URL-encoded query See CM Query Syntax Specification /changerequests?oslc_cm.query=<url-encoded-value>
oslc_cm.properties Comma-separated list of requested properties Used to retrieve only desired properties /changerequests?oslc_cm.properties=state,id,headline,owner
oslc_cm.pageSize Positive integer Specifies the maximum number of items to return in one response /changerequests?oslc_cm.pageSize=50

Namespaces Used

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

Prefix Namespace Defined
oslc_cm http://open-services.net/xmlns/cm/1.0/ Change Request Resource
Service Discovery Document
(this specification)
oslc_disc http://open-services.net/xmlns/discovery/1.0/ Service Provider Catalog
dc http://purl.org/dc/terms/ Dublin Core Terms
rdf http://www.w3.org/1999/02/22-rdf-syntax-ns# RDF/XML
atom http://www.w3.org/2005/Atom RFC4287 - Atom Syndication Format

Media Types Used

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

Media Type Defined Resource
application/x-oslc-cm-change-request+xml Change Request Resource Change Request Resource
application/x-oslc-cm-service-description+xml Service Discover Document Service Descriptor Document

application/x-oslc-disc-service-provider-catalog+xml

Service Provider Catalog Service Provider Catalog
application/atom+xml RFC4287 - Atom Syndication Format , RFC5005 - Feed Paging and Archiving Resource Collection
application/json RFC4627 - The application/json Media Type for JavaScript Object Notation (JSON) General JSON format request/response
application/xml
text/xml
W3C Extensible Markup Language (XML) 1..0 General XML format request/response
application/xhtml+xml W3C XHTML 1.1 XHTML presentation format for Change Request Resource
text/html W3C HTML 4 HTML presentation format for Change Request Resource

Requesting Formats

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.
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.
Each of the operation on a given URI may support a different default {mime-type}.

Selective Properties

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_cm.properties parameter on HTTP GET requests on individual resource requests as well as on Resource Collections. If the oslc_cm.properties parameter is omitted on the request, then all resource properties MUST be provided in the response.

If properties listed in the oslc_cm.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.

Parameter: oslc_cm.properties

Syntax:

BNF

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     ::= "*"

Sample:
Request the Change Request resource at /bugs/bug123 and only the properties of title and full owner details.

Request:

/bugs/bug123?oslc_cm.properties=dc:title,dc:owner{*}

Response:

<oslc_cm:ChangeRequest>
  <dc:title>A Defect</dc:title>
  <dc:owner>
    <name>John Doe</name>
    <email>foo@email.com</email>
  </dc:owner>
</oslc_cm:ChangeRequest>

Get a collection of change requests

GET {Simple Query URL}

Returns a collection of change requests. The service MUST support application/atom+xml and 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_cm.query. If this parameter is omitted, the server MAY respond with:

  • a page of results
  • reject the request with a HTTP response code of 403 Forbidden.
  • all results

Code Content Description
200 OK Per Accept header A collection of change requests with summary information and references to external change requests.
403 Forbidden Error message Server rejects request, as response content size many not be optimal.
406 Not Acceptable Error message Server can not fulfill the request due to it's Accept headers

Query Syntax

Change Requests can be queried using a HTTP GET-based method where query terms are URL-encoded.

Service providers MUST support the query syntax supported in the CmQuerySyntaxV1 specification.

Response Properties

Selected properties that are desired on the reponse of a GET on the Resource Collection CAN be specified using the oslc_cm.properties parameter with a comma separated list of property names.

Sample request:

 GET /changerequest?oslc_cm.query=state="open"&oslc_cm.properties=id,state,headline,severity,owner

Pagination

Resource Collection results SHOULD be limited in size by the request parameter oslc_cm:pageSize.

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

For application/atom+xml Resource Collections these is additional elements MUST be supported as defined in RFC5005 - Atom Feed Paging and Archiving:

  • 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 application/atom+xml Resource Collections these is additional elements SHOULD be supported:

  • oslc_cm: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_cm:pageSize=20, then oslc_cm:totalCount=200.

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

Create a new change request

Resource Creation

POST {Resource Creation URL}

Creates a new change request based using the content body from the request. The service MUST support application/x-oslc-cm-change-request+xml and application/ x-oslc-cm-change-request+ json for the request content body.

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

Status Code Response Content Description
201 Created HTTP-Header> Location: {New CR URI} A new change request resource has been created at the URI returned
400 Bad Request Error message

This response can be returned when any of the parameters are not properly structured. Some conditions when this can happen is:

  • malformed query parameters
  • malformed content (malformed XML)

404 Not Found Error message The request URL does not represent a URL on the server
409 Conflict Error message This response can be returned for any number of conditions:
  • Request content specifies a property that
    • the resource doesn't support
    • has an invalid value
415 Unsupported Media Type Error message If the Content-type of the body of the request is not known to the service provider

Get a change request

GET {CR URI}

Returns the change request resource from the URI given.

The service provider MUST support these media types for the response content body:

  • application/x-oslc-cm-change-request+xml
  • application/xml
  • text/xml
  • application/json
  • application/x-oslc-cm-change-request+json
  • text/html
  • application/xhtml+xml

A server provider MAY return an ETag HTTP header 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:

Code Content Description
200 OK Change Request resource A representation of the change request resource
404 Not Found Error message Either the root URI is invalid or the service can't locate the specified change request resource
405 Not Acceptable Error message Server can not fulfill the request due to it's Accept headers
410 Gone Error message The resource no longer exists in the system

Update a change request

PUT {CR URI}

Update the referenced change request resource with the request's body. The service MUST support application/x-oslc-cm-change-request+xml and application/x-oslc-cm-change-request+json for the request's content body.

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

Status Code Response Content Description
200 OK

<HTTP-Header> Location: {CR URI}

Content-body: updated CR

Once the change request is updated with the supplied changed, the resulting change request representation is returned
400 Bad Request Error message

This response can be returned when any of the parameters are not properly structured. Some conditions when this can happen is:

  • malformed query parameters
  • malformed content (malformed XML)
404 Not Found Error message The request URL does not represent a resource on the server
409 Conflict Error message This response can be returned for any number of conditions:
  • Request content specifies a property that
    • the resource doesn't support
    • has an invalid value
412 Precondition Failed Error message The ETag supplied in the If-Match request header value did not match that of the resource being modified.
415 Unsupported Media Type Error message  

Updating a change request resource involves replacing the current value with the value supplied.

Partial update of a change request

The request's change 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.

An abbreviated example where only the headline and state properties are updated could be:

PUT {CR URI}?oslc_cm.properties=headline,state
Content:
<oslc_cm:ChangeRequest>
  <headline>Parsing errors</headline>
  <state>Assigned</state>
</oslc_cm:ChangeRequest> 

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 409 Conflict must be returned.

Managing multi-valued properties and resource links

A typical change request resource will have certain properties that can contain multiple values and have linkages to a number of other resources. It is possible that these resource linkages, or relationships from the source change request, may be defined across service provider repositories. The resource relationship link is communicated as a resource URI along with resource metadata which provides a simple presentable label.

Example

Change request with a couple of referenced resources owner(internal) and blockedBy(External). Namespace definitions are omitted from the following examples.

GET /records/12234-123344?oslc_cm.properties=dc:owner,blockedBy
Accept: application/xml
Content: 
<oslc_cm:ChangeRequest>
    <dc:owner rdf:resource="/records/12234-123344" />
    <blockedBy oslc_cm:collref="/records/12234-123344/blockedBy"/>
</oslc_cm:ChangeRequest>

The introduction of oslc_cm:collref (collection resource) informs the client that the reference follows semantics of a collection of resources.

Operations supported on the oslc_cm:collref URI MUST be:

  • GET - retrieve the collection of links
  • POST - create a new entry
  • PUT - update the collection, replacing the resource collection with the request's content body

Individual entries in the collection are not modeled as uniquely identifiable resources (referencable by a URI)

From the example above, to request the collection of link resources (in other words, request the property blockedBy):

GET /records/12234-123344/blockedBy
Accept: application/xml
Content: 
<blockedBy oslc_cm:collref="/records/12234-123344/blockedBy">
  <blockedBy rdf:resource="/links/1255-235411" oslc_cm:label="Installation failures"/>
  <blockedBy rdf:resource="/links/123455-2344" oslc_cm:label="DB setup fails on 64 bit"/>
</blockedBy>

The addition of the OPTIONAL oslc_cm:label attribute allows for a label for the resource reference that can be used in user displays.

Delete a change request

DELETE {CR URI}

Delete the change request represented by the given URL. Service providers MAY support a DELETE request on Change Request Resources. 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:

Code Content Description
200 OK none The service has marked the resource as deleted or physically has deleted the resource

Delegated change request actions

Most change management service providers have Web-based UI that can perform complex actions for handling of rules needed for creation change request resources as well as search and query methods needed to locate them. Clients of these services can utilize this capability within their own Web UI by following some simple standards-based methods for cross application interaction. This is interaction is detailed in a separate specification document titled Delegated Resource Selection and Creation. Conforming clients and service providers MUST support this delegated model.

Security and Authentication

Service providers and consumers SHOULD support HTTP basic authentication.

Service providers and consumers SHOULD support OAuth.

Service providers and consumers SHOULD use the secure communication protocol HTTPS (HTTP interaction using Transport Layer Security).

Error Status Information

Whenever an HTTP request results in an error, a status code in the range of 400-599 is returned from the server. A service provider returns a response message body with additional information about the error. The response's body content type corresponds the requested content, for example if the resource requested application/json format and an error occurs, the error information will be in the application/json format as well.

The properties in the error response MUST be defined in the http://open-services.net/xmlns/cm/1.0 namespace.

Error response properties:

  • oslc_cm:statusCode - required element containing HTTP status code cooresponding to this request
  • oslc_cm:message - required element containing an error message string suitable for presentation to a user of the client
  • oslc_cm:url - optional element whose string content is a URL indicating a Web presentation giving more information on the error
    • oslc_cm:rel - optional attribute with value of "alternate" indicating that it is an alternate method to resolve the error
    • oslc_cm:hintWidth - optional attribute
    • oslc_cm:hintHeight - optional attribute

Implementations are may provide additional properties. The error message text must be in the appropriate locale specified in the request.

If the requested content type is of a presentation format such as application/xhtml+xml and text/html, there are no required additional properties for the response message body.

Error status examples:

In application/xml format:

<oslc_cm:Error>
    <oslc_cm:statusCode>404</oslc_cm:statusCode>
    <oslc_cm:message>
        A Defect with the given ID 1234 wasn't found on this server.
    </oslc_cm:message>
</oslc_cm:Error>

In application/json format:

{
  "oslc_cm:statusCode": "404",
  "oslc_cm:message": "A Defect with the given ID 1234 wasn't found on this server."
}

Resource Formats

References

Topic revision: r65 - 28 Jul 2009 - 19:38:50 - TWikiAdminUser
Main.CmRestApiV1 moved from Main.CmRestApi on 28 May 2009 - 14:12 by ScottBosworth - put it back
 
This site is powered by the TWiki collaboration platform 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