Requirements Management REST API

1.0 SPECIFICATION

Introduction

This specification defines a resource model of requirements and other artefacts from the domain of requirements definition and management. The resource model is defined in terms of representations of resources, media types, the basic HTTP 1.1 methods and response codes. The capabilities of this "RESTful" API is not declared nor intended to be general purpose; they are driven by a set of scenarios that were the focus of the work group which authored this specification.

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.

Core resource summary

Resource	URI	GET	POST	PUT	DELETE	Description
Requirement	{URI}	MUST	Undefined	MUST	MAY	Representation of a requirement (see Requirement resource)
Requirement Collection	{URI}	MUST	Undefined	MUST	MAY	A collection of references to requirements (see Requirement Collection resource)

Creation and Selection of Resources

The RM resource model supports the creation of certain resources via "factory" resources. Requirements can also be created via delegated web UIs. Details of each of these capabilities will follow in subsequent sections; the following table provides a summary:

Purpose	Resource	URL	Support
Requirement Creation	oslc_rm:requirementFactory	{Requirement Factory}	MUST
Requirement Selection UI	oslc_rm:requirementSelectionDialog in service discovery document	{Requirement Selection URL}	MUST
Requirement Creation UI	oslc_rm:requirementCreationDialog in service discovery document	{Requirement Creation URL}	MUST
Requirement Collection Selection UI	oslc_rm:requirementCollectionSelectionDialog in service discovery document	{Collection Selection URL}	MUST

Namespaces Used

The following 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_rm	http://open-services.net/xmlns/rm/1.0/	By 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
rdfs	http://www.w3.org/2000/01/rdf-schema#	RDF Schema

Media Types Used

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

Media Type	Defined	Resource
application/x-oslc-rm-service-description-1.0+xml	Service Discovery Document	Service Description Document
application/x-oslc-disc-service-provider-catalog+xml	Service Provider Catalog	Service Provider Catalog
application/x-oslc-rm-requirement-1.0+xml	Requirement Resource Definition	Requirement.
application/x-oslc-rm-requirement-collection-1.0+xml	Requirement Collection Resource Definition	Requirement collection.
application/xml text/xml	W3C Extensible Markup Language (XML)	General XML format request/response
application/xhtml+xml	W3C XHTML 1.1	XHTML presentation format
text/html	W3C HTML 4	HTML presentation format
application/rdf+xml	RDF/XML media type	General XML representation of RDF

General Remarks

Service providers MUST follow the HTTP/1.1 (RFC 2616) specification.

In particular:

• Providers MUST support server-side content negotiation using the HTTP standard Accept header as per the HTTP/1.1 specification. If an Accept header is supplied and has more than one MIME type, then the server will determine the MIME type to be used for the response entity. If none is provided then a default is used, appropriate to the resource URI. If the requested MIME type is unknown, a HTTP response code of 415 Unsupported Media Type MUST be returned.
• Servers MUST correctly use the standard HTTP response codes - resource-specific interpretation of response codes is given elsewhere in this specification, on a resource-by-resource, method-by-method basis.

Providers implementing this specification SHOULD refrain from inventing MIME types with a subtype having "x-oslc-" as a prefix, which have not been defined by OSLC specifications. In this way providers can offer representations that are not defined by this specification, but in a safe way which will avoid collision with OSLC-defined MIME types that may appear in future revisions of OSLC specifications.

Each of the operations on a given URI may support a different default MIME type, as described elsewhere in this specification.

HEAD behaves as GET in all cases, with the exception that the response entity is omitted in the case of HEAD.

Required and read-only resource properties

The resource model describes properties as

• "required on read" or "not required on read"
• "required on write", or "not required on write"

Each resource representation describes various properties, their meaning, and behaviour on read (GET/HEAD) and write (POST/PUT).

A provider MUST respond with a 400 (Forbidden) when a service consumer attempts to update a resource (using POST/PUT) with a representation where one or more "required on write" properties is absent. A provider MUST tolerate an update (a POST/PUT) to a resource with a representation regardless of whether any "not required on write" properties are absent.

A provider MUST include in all resource representations those "required on read" properties (on GET/HEAD). Properties which are "not required on read" MAY be excluded.

This specification defines the meaning of several properties in the RM resource model, some of which are declared to be "not required on read". The RM resource model specification is open (in the sense that providers MAY contribute properties from other vocabularies, and providers MAY tolerate clients contributing properties from other vocabularies): such foreign properties MUST be treated as "not required on read", and "required on write".

Compliance

All implementations of this interface MUST implement all of the REQUIRED behaviours. Such implementations are termed "conditionally compliant". Implementations which additionally implement all of the OPTIONAL behaviours are "unconditionally compliant".

Certain facets of behaviour are explicitly left "undefined" by this specification; providers are free to implement any behaviour in such cases. However, clients consuming OSLC RM services are strongly recommended not to exploit or to rely on such behaviours since future revisions of this specification may require compliant implementations to change those behaviours. (Notice as a special case that service providers may choose to implement "undefined" in this specification as "405 (Method Not Allowed)": consumer reliance on this response code would be contrary to this recommendation.)

Resource Model

Requirement Resource

Requirement resource formats are defined elsewhere in this specification (see requirement resources).

The following table describes HTTP methods on requirement resources:

Method	Required	Comments
GET/HEAD	MUST	Fetches a representation of the requirement [1].
PUT	MUST	Updates the resource with the supplied representation [1,2].
POST	Undefined	The behaviour of a POST to a requirement resource is not defined by this specification.
DELETE	MAY	Deletes the resource [3].

Notes:

1. Providers MUST support application/x-oslc-rm-requirement-1.0+xml media type for requirement resources. The behaviour with other media types is not defined by this specification.

2. A service provider MUST support at least the following HTTP response status codes in response to a PUT to a requirement resource:

   Code	Content	Description
   403 (Forbidden)	Error message	The request is well-formed but is invalid in some other way. This request should not be retried. (This would happen if the requirement representation were missing one or more of its required properties.)
   404 (Not found)	Error message	The request URI was not found on the server.
   406 (Not Acceptable)	Error message	The supplied media type is not acceptable as a representation of a requirement. A list of acceptable content types SHOULD be supplied in the response entity.
   409 (Conflict)	Error message	The request is well-formed but is invalid in some other way. A description of the problem MAY be provided in the response body.
   415 (Unsupported Media Type)	Error message	The Content-Type of the request is not recognised by the server. The provider SHOULD provide a list of acceptable content types in the response body.

3. Providers MAY support DELETE on requirement resources. Those which do not support DELETE on a requirement resource MUST respond with a 405 (Method Not Supported). A successful deletion SHOULD cause subsequent requests to access that resource to return a 404 (Not Found) or 410 (Gone). Service consumers may use OPTIONS to determine whether or not a provider supports DELETE on a requirement by doing an OPTIONS on a URI "*" with Content-Type set to application/x-oslc-rm-requirement-1.0+xml. Providers supporting DELETE MUST indicate in the OPTIONS response whether or not DELETE is supported.

Requirement Factory

Requirements are created by POSTing an application/x-oslc-rm-requirement-1.0+xml resource representation to the {Requirement Factory} URI described in the service document. Service providers MUST support this media type on POST. Requirement resource formats are defined elsewhere in this specification (see requirement resources).

The following table describes the HTTP methods on the {Requirement Factory}:

Method	Required	Comment
GET/HEAD	Undefined	[1]
PUT	MUST	Returns 405 (Method Not Allowed) [2]
POST	MUST	Creates a new requirement [3].
DELETE	MUST	Returns 405 (Method Not Allowed) [2]

Notes:

1. The behaviour of GET on the {Requirement Factory} is undefined.
2. PUT/DELETE on {Requirement Factory} is not allowed and MUST result in a 405 (Method Not Allowed) for all media types.
3. The provider MUST support application/x-oslc-rm-requirement-1.0+xml media type on POST. The behaviour with other media types is not defined by this specification. Additional details on POST are given below.

A service provider MUST support at least the following HTTP response status codes in response to a POST to the {Requirement Factory}:

Code	Content	Description
201(Created)	Requirement resource	Representation of the created requirement. The Location header MUST contain the URI of the newly created requirement [1].
400 (Bad request)	Error message	The POST could not be processed because the request was not well-formed.
403 (Forbidden)	Error message	The request is well-formed but is invalid in some other way. This request should not be retried. (This would happen if the requirement representation were missing one or more of its required properties.)
404 (Not found)	Error message	The request URI was not found on the server.
406 (Not Acceptable)	Error message	The supplied media type is not acceptable as a representation of a requirement. A list of acceptable media types SHOULD be supplied in the response entity.
409 (Conflict)	Error message	The request is well-formed but is invalid in some other way. A description of the problem MAY be provided in the response body.
415 (Unsupported Media Type)	Error message	The Content-Type of the request is not recognised by the server. The provider SHOULD provide a list of acceptable content types in the response body.

Notes:

1. The rdf:about property in the POSTed requirement resource representation MAY be ignored. This specification does not provide a means for the client to propose a URI for the newly created requirement resource (for example, using rdf:about or a "Name" header in the HTTP request). It is recommended that clients POST representations containing rdf:about="".

Requirement Collection Resource

Requirement collection resource formats are defined elsewhere in this specification (see requirement collection resources).

The following table describes operations on requirement collection resources:

Method	Required	Comments
GET/HEAD	MUST	Fetches a representation of the collection [1].
PUT	MUST	Updates a the collection resource [2,3].
POST	Undefined
DELETE	MAY	Deletes the collection resource [4].

Notes:

1. Providers MUST support application/x-oslc-rm-requirement-collection-1.0+xml content type for requirement collection resources. The behaviour with other media types is not defined by this specification.
2. Provides MUST support application/x-oslc-rm-requirement-collection-1.0+xml content type for requirement collection resources. The behaviour with other media types is not defined by this specification. Sservice provider MUST support at least the following HTTP response status codes in response to a PUT to a requirement collection resource:

3. Code	Content	Description
   403 (Forbidden)	Error message	The request is well-formed but is invalid in some other way. This request should not be retried. (This would happen if the requirement representation were missing one or more of its required properties.)
   404 (Not found)	Error message	The request URI was not found on the server.
   406 (Not Acceptable)	Error message	The supplied media type is not acceptable as a representation of a requirement collection. A list of acceptable content types SHOULD be supplied in the response entity.
   409 (Conflict)	Error message	The request is well-formed but is invalid in some other way. A description of the problem MAY be provided in the response body.
   415 (Unsupported Media Type)	Error message	The Content-Type of the request is not recognised by the server. The provider SHOULD provide a list of acceptable content types in the response body.

4. Providers MAY support DELETE on a requirement collection resource. Providers which do not support DELETE MUST respond with a 405 (Method Not Allowed). A successful resource deletion SHOULD cause subsequent access to that requirement collection resource to yield a 410 (Gone) or a 404 (Not Found). This specification leaves as Undefined the effect upon the requirements referenced by a collection when that collection is successfully deleted. (In particular, services consumers must not assume that deleting a collection will delete each of the requirements contained in that collection.) Service consumers should use OPTIONS to determine whether or not a provider supports DELETE on a requirement collection by doing an OPTIONS on a URI "*" with Content-Type set to application/x-oslc-rm-requirement-collection-1.0+xml. Providers MUST indicate in the OPTIONS response whether or not DELETE is supported.

Delegated RM request actions

Some requirements management service providers have Web-based UI that can perform complex actions for handling of rules needed for selection of requirements, for example, providing navigation, query and search capabilities to locate requirements and collections of requirements. 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 service providers MUST support this delegated model.

Security and Authentication

Service providers and consumers MAY support HTTP basic authentication.

Service providers and consumers MAY support OAuth.

Service providers and consumers MAY 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 body containing additional information about the error. The response's body media type MUST be application/rdf+xml, with the following properties defined in the http://open-services.net/xmlns/rm/1.0 namespace:

• oslc_rm:statusCode - required element containing HTTP status code corresponding to this request (this is a replication of the code in the response status line).
• oslc_rm:message - required element containing an error message string suitable for presentation to a user of the client
• oslc_rm:url - optional element whose string content is a URL indicating a Web presentation giving more information on the error
  • oslc_rm:rel - optional attribute with value of "alternate" indicating that it is an alternate method to resolve the error
  • oslc_rm:hintWidth - optional attribute
  • oslc_rm:hintHeight - optional attribute

Implementations MAY provide additional properties. The error message text SHOULD be appropriate to the locale of the requesting client.

Error status examples:

In application/rdf+xml format:

<?xml version="1.0" encoding="UTF-8"?>
<rdm:Error
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:rdm="http://open-services.net/xmlns/rm/1.0/">
   <rdm:statusCode>404</rdm:statusCode>
    <rdm:message>
       A requirement with the given URI wasn't found on this server.
    </rdm:message>
</rdm:Error>

References

• HTTP/1.1 (RFC2616)
• IANA MIME Media Types
• RM Service Description
• Requirement Resource Definition
• Requirement Collection Resource Definition
• Delegated Resource Selection and Creation
• OSLC Service Provider Catalog