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

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

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

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

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:

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:

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

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:

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

• OSLC QM resource definition specification
• OSLC QM service description document

References

• RFC2616 HTTP
• OSLC QM Use Cases & Scenarios?