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.

Quality Management REST API

1.0 SPECIFICATION

Introduction

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 RFC2119. Domain name examples use 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 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 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} Create a new QM resource REQUIRED
Resource Query <simpleQuery> {Simple Query URL} Get a collection of QM resources 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) is used. Subsequent sections will define their usage.

Parameter Value Description Sample
oslc_qm.query URL-encoded query 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/ QM Resources
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-qm-testplan-1.0+xml QM Resource Test Plan Resource
application/x-oslc-qm-testcase-1.0+xml QM Resource Test Case Resource
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/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 QM Resource
text/html 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

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

Sample:
Request the test plan resource at /testplan/mytestplan123 and only the properties of title and full owner details.

Request:

/testplan/mytestplan123?oslc_qm.properties=dc:title,dc:owner

Response:

<oslc_qm:testplan>
  <dc:title>My test plan</dc:title>
  <dc:owner>foo@email.com</dc:owner>
</oslc_qm:testplan>

Get a collection of QM resources

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 oslc_qm.properties parameter with a comma separated list of property names.

Sample request:

 GET /testplan?oslc_qm.query=dc:description="xyz"&oslc_qm.properties=dc:identifier,dc:owner

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 section 3 of the 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

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:
  • 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 resource

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

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}

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:
  • 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 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

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:

PUT {QM URI}?oslc_qm.properties=dc:title
Content:
<oslc_qm:testplan>
  <dc:title>new title</dc:title>
</oslc_qm:testplan> 

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

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

Resource Formats

References

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