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
>
QmSpecificationV1
>
QmRestApiV1
(26 Jan 2010,
TWikiAdminUser
)
(raw view)
<h1 id="titleL2-community">Quality Management REST API</h1> _1.0 SPECIFICATION_ %TOC% ---++ Introduction<a name="intro" title="intro"></a> Quality Management resources define the test plans, test cases, activities and tasks encountered during the testing phase of the software delivery lifecycle. 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 quality 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 *Service Provider* - an implementation of the OSLC Quality Management (QM) specifications as a server. OSLC QM clients consume these services *Test Plan Resource* - Used to define the overall process and strategy for testing a system. *Test Case Resource* - Used to determine whether the system exhibits the correct behavior under a specific set of circumstances. *Resource Collection* - An ordered or unordered set of resources, typically generated as the result of performing a query or search. *QM Resource* - A resource managed by the QM service provider. The two types of resources defined by this specification are Test Plan and Test Case. ---++ Summary ---+++ Resource URIs and Methods | *Resource* | *URI* | *GET* | *POST* | *PUT* | *DELETE* | *Description* | | Collection of Resources | {Collection URI} | Y | * | N | N | A collection of QM resources | | Resource | {Resource URI} | Y | N | Y | Y | An identifiable QM resource, by a permanant URI | * - the collection MAY support creation on its URI, see [[#QMcreate][Create a new resource]] 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 QM resources The following table outlines the key items that are exposed in the QM 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} | [[#QMcreate][Create a new QM resource]] | REQUIRED | | Resource Query | <simpleQuery> | {Simple Query URL} | [[#getcollection][Get a collection of QM resources]] | REQUIRED | | Resource Selection UI | <selectionDialog> | {Selection Dialog URL} | [[QmDelegatedResourceSelectionAndCreationV1#Resource_Selection][Resource Selection]] | REQUIRED | | Resource Creation UI | <creationDialog> | {Creation Dialog URL} | [[QmDelegatedResourceSelectionAndCreationV1#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) is used. Subsequent sections will define their usage. | *Parameter* | *Value* | *Description* | *Sample* | | oslc_qm.query | URL-encoded query | [[QmQuerySyntaxV1][See QM Query Syntax Specification]] | /testplan?oslc_qm.query=<url-encoded-value> | | oslc_qm.properties | Comma-separated list of requested properties | Used to retrieve only desired properties | /testplan/1?oslc_qm.properties=dc:owner,dc:title,dc:description | | oslc_qm.pageSize | Positive integer | Specifies the maximum number of items to return in one response | /testplan/1?oslc_qm.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_qm | http://open-services.net/xmlns/qm/1.0/ | [[QmResourceDefinitionsV1][QM Resources]]<br />[[QmServiceDescriptionV1][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-qm-testplan-1.0+xml | [[QmResourceDefinitionsV1][QM Resource]] | Test Plan Resource | | application/x-oslc-qm-testcase-1.0+xml | [[QmResourceDefinitionsV1][QM Resource]] | Test Case Resource | | application/x-oslc-disc-service-provider-catalog+xml | [[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/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 QM Resource | | text/html | [[http://www.w3.org/TR/html401/][W3C HTML 4]] | HTML presentation format for QM Resource | ---++ Requesting Formats There will be a single supported method for a client to designate its required response format, using the HTTP request header of Accept. If an Accept header is supplied that has more than one {mime-type}, then the server MAY determine the {mime-type} that will be used for the response content type from any in the supplied list. If no Accept header is provided then a default of application/xml MUST be used, unless defined otherwise. If the requested {mime-type} is unknown, a HTTP response code of 415 Unsupported Media Type MUST be returned. Each of the operations 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_qm.properties= parameter on HTTP GET requests on individual resource requests as well as on Resource Collections. If the =oslc_qm.properties= parameter is omitted on the request, then all resource properties MUST be provided in the response. If properties listed in the oslc_qm.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_qm.properties= *Syntax:* *BNF* <verbatim>properties ::= property ("," property)* property ::= identifier | nested_prop | wildcard identifier ::= word (":" word)? word ::= /any sequence of letters and numbers, starting with a letter/ nested_prop ::= property "{" properties "}" wildcard ::= "*"</verbatim> <strong>Sample:<br /></strong>Request the test plan resource at /testplan/mytestplan123 and only the properties of title and full owner details. *Request:* <verbatim>/testplan/mytestplan123?oslc_qm.properties=dc:title,dc:owner</verbatim> *Response:* <verbatim><oslc_qm:testplan> <dc:title>My test plan</dc:title> <dc:owner>foo@email.com</dc:owner> </oslc_qm:testplan> </verbatim> ---++ Get a collection of QM resources <a name="getcollection" title="getcollection"></a> =GET {Simple Query URL}= Returns a collection of QM resources. The service MUST support =application/atom+xml= for the response content body. If the client provides an Accept header which does not include =application/atom+xml= then the server MUST return 406 Not Acceptable. The number of entries in the collection response is determined by HTTP query parameter =oslc_qm.pageSize=. If this parameter is omitted, the server MAY respond with: * all results and HTTP response code of =200 OK=. * the first page of results and HTTP response code of =200 OK=. * reject the request and HTTP response code of =403 Forbidden=. ---+++ *Query Syntax* QM resources 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 QmQuerySyntaxV1 specification. ---+++ Response Properties Selected properties that are desired on the response of a GET on the Resource Collection CAN be specified using the [[#Selective_Properties][ =oslc_qm.properties= parameter]] with a comma separated list of property names. Sample request: <verbatim> GET /testplan?oslc_qm.query=dc:description="xyz"&oslc_qm.properties=dc:identifier,dc:owner</verbatim> ---+++ Pagination Resource Collection results SHOULD be limited in size by the request parameter =oslc_qm:pageSize=. Subsequent pages MUST be able to be requested using pagination elements in the Resource Collection response content. For application/atom+xml Resource Collections the pagination elements MUST follow [[http://tools.ietf.org/html/rfc5005#section-3][section 3]] of the [[http://tools.ietf.org/html/rfc5005][ATOM Feed Paging and Archiving specification]] In addition to the ATOM paging specification the following additional elements SHOULD be supported: * =oslc_qm: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_qm:pageSize=20, then oslc_qm:totalCount=200. ---++ Create a new QM resource <a name="QMcreate" title="QMcreate"></a> ---+++ Resource Creation =POST {Resource Creation URL}= Creates a QM resource based using the content body from the request. The service MUST support the following content types for the request's content body: * =application/x-oslc-qm-testplan-1.0+xml= for test plan creation * =application/x-oslc-qm-testcase-1.0+xml= for test case creation A service provider MUST support at least the following HTTP response status codes: | *Status Code* | *Response Content* | *Description* | | 201 Created | HTTP-Header> Location: {New QM URI} | A new QM 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. Sending malformed content (malformed XML) in the request body can also lead to this response. | | 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 resource <a name="QMget" title="QMget"></a> =GET {QM URI}= Returns the resource from the URI given. The service provider MUST support these media types for the response content body: * =application/x-oslc-qm-testplan-1.0+xml= * =application/x-oslc-qm-testcase-1.0+xml= * =application/xml= * =text/xml= * =application/xhtml+xml= See related standard which describes usage of [[http://tools.ietf.org/html/rfc2616#section-14.19][ =ETag= HTTP header]] for concurrent modification detection. A service provider MUST support at least the following HTTP response status codes: | *Code* | *Content* | *Description* | | 200 OK | QM resource | A representation of the QM resource | | 404 Not Found | Error message | Either the root URI is invalid or the service can't locate the specified resource | | 406 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 resource <a name="QMupdate" title="updateQM"></a> =PUT {QM URI}= Update the referenced QM resource with the request's body. The service MUST support the following content types for the request's content body: * =application/x-oslc-qm-testplan-1.0+xml= for test plan updation * =application/x-oslc-qm-testcase-1.0+xml= for test case updation A service provider MUST support at least the following HTTP response status codes: | *Status Code* | *Response Content* | *Description* | | 200 OK | <HTTP-Header> Location: {QM URI}</p><p>Content-body: updated QM resource | Once the resource is updated with the supplied changed, the resulting resource representation is returned | | 400 Bad Request | Error message | This response can be returned when any of the parameters are not properly structured. Sending malformed content (malformed XML) in the request body can also lead to this response. | | 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 | If the Content-type of the body of the request is not known to the service provider | Updating a resource involves replacing the current value with the value supplied. ---+++ Partial update of a resource <a name="QMpartialupdate" title="partialupdateQM"></a> The representation of the resource provided in the body of the request 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 title property is updated could be: <verbatim>PUT {QM URI}?oslc_qm.properties=dc:title Content: <oslc_qm:testplan> <dc:title>new title</dc:title> </oslc_qm:testplan> </verbatim> If the parameter =oslc_qm.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_qm.properties= contains an invalid resource property, then a =409 Conflict= must be returned. ---++ Delete a resource<a name="QMdelete" title="QMdelete"></a> DELETE ={QM URI}= Delete the resource represented by the given URL. Service providers MAY support a DELETE request on QM 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 | | 404 Not Found | Error message | The request URL does not represent a resource on the server | ---++ Delegated resource actions Quality Management tools often have web-based UIs that allow users to create or locate QM Resources. These UIs can perform complex handling of rules associated with resource creation and can also handle search and query methods for locating the resources. The OSLC-QM specification includes services that allow client tools to utilize these QM tool capabilities within their own Web UIs using some simple standards-based methods for cross application interaction. This interaction is detailed in a separate document titled [[QmDelegatedResourceSelectionAndCreationV1][Delegated Resource Selection and Creation]]. OSLC-QM compliant 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]]). ---+++ Resource Formats * [[QmResourceDefinitionsV1][OSLC QM resource definition specification]] * [[QmServiceDescriptionV1][OSLC QM service description document]] ---++ References * [[http://www.ietf.org/rfc/rfc2616.txt][RFC2616 HTTP]] * [[QmScenarios][OSLC QM Use Cases & Scenarios]]
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r23
<
r22
<
r21
<
r20
<
r19
|
B
acklinks
|
V
iew topic
|
Ra
w
edit
|
M
ore topic actions
Topic revision: r23 - 26 Jan 2010 - 17:37:43 -
TWikiAdminUser
Main.QmRestApiV1 moved from Main.QmRestApi on 03 Nov 2009 - 16:50 by
PaulMcMahan
-
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