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.

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 DefinedSorted ascending
oslc_rm http://open-services.net/xmlns/rm/1.0/ By this specification
dc http://purl.org/dc/terms/ Dublin Core Terms
rdfs http://www.w3.org/2000/01/rdf-schema# RDF Schema
rdf http://www.w3.org/1999/02/22-rdf-syntax-ns# RDF/XML
oslc_disc http://open-services.net/xmlns/discovery/1.0/ Service Provider Catalog

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:

    CodeContentDescription
    403 (Forbidden)Error messageThe 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 messageThe request URI was not found on the server.
    406 (Not Acceptable)Error messageThe 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 messageThe 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 messageThe 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. CodeContentDescription
    403 (Forbidden)Error messageThe 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 messageThe request URI was not found on the server.
    406 (Not Acceptable)Error messageThe 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 messageThe 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 messageThe 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

Topic revision: r64 - 08 Mar 2010 - 20:41:31 - TWikiAdminUser
Main.RmRestApiV1 moved from Main.RmRestApi on 27 Nov 2009 - 05:43 by IanGreen - 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