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

* - 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.

* 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.pageSize	Positive integer	Specifies the maximum number of items to return in one response	/changerequests?oslc_cm.pageSize=50
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.query	URL-encoded query	See CM Query Syntax Specification	/changerequests?oslc_cm.query=<url-encoded-value>

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.

Media Types Used

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

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

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.

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:

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:

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:

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:

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

• OSLC CM resource definition specification
• OSLC CM service description document
• OSLC CM JSON

References

• RFC2616 HTTP
• OSLC CM Use Cases & Scenarios