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
>
CmHome
>
CmSpecificationV1
>
CmRestApiV1
(28 Jul 2009,
TWikiAdminUser
)
(raw view)
<h1 id="titleL2-community">Change Management REST API</h1> _1.0 SPECIFICATION_ %TOC% ---++ Introduction<a name="intro" title="intro"></a> 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 [[http://www.ietf.org/rfc/rfc2119.txt][RFC2119]]. Domain name examples use [[http://tools.ietf.org/html/rfc2606][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][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://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html][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][Create a new Change Request]] | REQUIRED | | Resource Query | <simpleQuery> | {Simple Query URL} | [[#Get_a_collection_of_change_reque][Get a Collection of Change Requests]] | REQUIRED | | Resource Selection UI | <selectionDialog> | {Selection Dialog URL} | [[#Resource_Selection][Resource Selection]] | REQUIRED | | Resource Creation UI | <creationDialog> | {Creation Dialog URL} | [[#Resource_Creation][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 | [[CmQuerySyntaxV1][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/ | [[CmResourceDefinitionsV1][Change Request Resource]]<br />[[CmServiceDescriptionV1][Service Discovery Document]]<br />(this specification) | | oslc_disc | http://open-services.net/xmlns/discovery/1.0/ | [[OslcServiceProviderCatalogV1][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 | [[http://tools.ietf.org/html/rfc4287][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 | [[CmResourceDefinitionsV1][Change Request Resource]] | Change Request Resource | | application/x-oslc-cm-service-description+xml | [[CmServiceDescriptionV1][Service Discover Document]] | Service Descriptor Document | | <p>application/x-oslc-disc-service-provider-catalog+xml </p> | [[OslcServiceProviderCatalogV1][Service Provider Catalog]] | Service Provider Catalog | | application/atom+xml | [[http://tools.ietf.org/html/rfc4287][RFC4287 - Atom Syndication Format]] , [[http://tools.ietf.org/html/rfc5005][RFC5005 - Feed Paging and Archiving]] | Resource Collection | | application/json | [[http://tools.ietf.org/html/rfc4627][RFC4627 - The application/json Media Type for JavaScript Object Notation (JSON)]] | General JSON format request/response | | application/xml<br />text/xml | [[http://www.w3.org/TR/xml/][W3C Extensible Markup Language (XML) 1..0]] | General XML format request/response | | application/xhtml+xml | [[http://www.w3.org/TR/xhtml11/][W3C XHTML 1.1]] | XHTML presentation format for Change Request Resource | | text/html | [[http://www.w3.org/TR/html401/][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.<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}. ---+++ 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* <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> <strong>Sample:<br /></strong>Request the Change Request resource at /bugs/bug123 and only the properties of title and full owner details. *Request:* <verbatim>/bugs/bug123?oslc_cm.properties=dc:title,dc:owner{*}</verbatim> *Response:* <verbatim><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> </verbatim> ---++ Get a collection of change requests <a name="getcollection" title="getcollection"></a> =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 [[#Selective_Properties][ =oslc_cm.properties= parameter]] with a comma separated list of property names. Sample request: <verbatim> GET /changerequest?oslc_cm.query=state="open"&oslc_cm.properties=id,state,headline,severity,owner</verbatim> ---+++ 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 [[http://tools.ietf.org/html/rfc5005][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 [[CmJsonFormatV1][JSON format]] MUST be supported. ---++ Create a new change request <a name="CRcreate" title="CRcreate"></a> ---+++ 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 | <p>This response can be returned when any of the parameters are not properly structured. Some conditions when this can happen is:</p><ul><li>malformed query parameters</li><li>malformed content (malformed XML)</li></ul><p> </p> | | 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:<br /><ul><li>Request content specifies a property that<ul><li>the resource doesn't support</li><li>has an invalid value </li></ul></li></ul> | | 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 <a name="CRget" title="CRget"></a> =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 [[http://tools.ietf.org/html/rfc2616#section-14.19][ =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 <a name="CRupdate" title="updateCR"></a> =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 | <p><HTTP-Header> Location: {CR URI}</p><p>Content-body: updated CR </p> | Once the change request is updated with the supplied changed, the resulting change request representation is returned | | 400 Bad Request | Error message | <p>This response can be returned when any of the parameters are not properly structured. Some conditions when this can happen is:</p><ul><li>malformed query parameters</li><li>malformed content (malformed XML)</li></ul> | | 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:<br /><ul><li>Request content specifies a property that<ul><li>the resource doesn't support</li><li>has an invalid value </li></ul></li></ul> | | 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 <a name="CRpartialupdate" title="partialupdateCR"></a> 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: <verbatim>PUT {CR URI}?oslc_cm.properties=headline,state Content: <oslc_cm:ChangeRequest> <headline>Parsing errors</headline> <state>Assigned</state> </oslc_cm:ChangeRequest> </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 =409 Conflict= must be returned. ---++ Managing multi-valued properties and resource links<a name="CRlink" title="CRlink"></a> 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. <verbatim>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> </verbatim> 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): <verbatim>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> </verbatim> 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<a name="CRdelete" title="CRdelete"></a> 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 [[CmDelegatedResourceSelectionAndCreationV1][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://tools.ietf.org/html/rfc2617][HTTP basic authentication]]. Service providers and consumers SHOULD support [[http://oauth.net/][OAuth]]. Service providers and consumers SHOULD use the secure communication protocol HTTPS (HTTP interaction using [[http://tools.ietf.org/html/rfc5246][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: <verbatim style="margin: 1em 0px; overflow: scroll; font-family: 'Courier New',courier,monaco,monospace; font-size: 12pt; width: auto; color: #7a4707; background-image: url('http://open-services.net/pub/TWiki/TinyMCEPlugin/verbatim.gif')"><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></verbatim> In =application/json= format: <verbatim style="margin: 1em 0px; overflow: scroll; font-family: 'Courier New',courier,monaco,monospace; font-size: 12pt; width: auto; color: #7a4707; background-image: url('http://open-services.net/pub/TWiki/TinyMCEPlugin/verbatim.gif')">{ "oslc_cm:statusCode": "404", "oslc_cm:message": "A Defect with the given ID 1234 wasn't found on this server." }</verbatim> ---+++ Resource Formats * [[CmResourceDefinitionsV1][OSLC CM resource definition specification]] * [[CmServiceDescriptionV1][OSLC CM service description document]] * [[CmJsonFormatV1][OSLC CM JSON]] ---++ References * [[http://www.ietf.org/rfc/rfc2616.txt][RFC2616 HTTP]] * [[CmScenarios][OSLC CM Use Cases & Scenarios]]
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r65
<
r64
<
r63
<
r62
<
r61
|
B
acklinks
|
V
iew topic
|
Ra
w
edit
|
M
ore topic actions
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
Main
Main Web
Create New Topic
Index
Search
Changes
Notifications
RSS Feed
Statistics
Preferences
Webs
Main
Sandbox
TWiki
Български
Cesky
Dansk
Deutsch
English
Español
Français
Italiano
日本語
Nederlands
Polski
Português
Русский
Svenska
简体中文
簡體中文
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