This API is characterized by the ability for a client to specify the URI on
an HTTP PUT request and is described completely in the detailed specification
below. The API treats URIs as opaque only requiring that they be
rooted in the resource path which a client should use based on discovery.
The resulting URI namespace is discontiguous, that is the path segments of a
URI do not require hierarchical storage; this also implies there is no
mechanism to traverse the URI namespace.
Motivation
This API provides the client maximum flexibility in defining the storage
layout for an application but puts the burden on clients to track and assign
URLs to resources they create. This is in contrast to the collection storage which allows the server
to assign URLs to resources created within the scope of a collection.
Specification
The specification for the simple resource storage relies on the client
providing the {resource-uri} in all cases.
Method
URL
Comments
GET/HEAD
{resource-uri}
Returns either the stored resource with a status code of 200 (OK) or
204 (no content), or one of the following errors: 304 (unmodified), 401
(unauthorized), 403 (forbidden), 404 (not found), 410 (gone), 500
(server error) or 503 (service unavailable).
POST
{resource-uri}
Not permitted - returns 405 (Method not allowed).
PUT
{resource-uri}
Returns either 201 (created) for a new resource or 200 (OK) on update
of an existing resource. The server may return one of the following
errors: 400 (bad request), 401 (unauthorized), 403 (forbidden), 409
(conflict), 500 (server error) or 503 (service unavailable).
DELETE
{resource-uri}
Returns a status code of 200 (OK), or one of the following errors:
304 (unmodified), 400 (bad request), 401 (unauthorized), 403
(forbidden), 404 (not found), 410 (gone), 409 (conflict), 500 (server
error) or 503 (service unavailable).
Notes:
Clients MUST have the Reader role to perform a GET or HEAD method and
MUST have Writer role to perform PUT or DELETE.
A successful GET or HEAD MUST return, in the Content-Location header, the
revision-specific URL to the resource.
A successful HEAD MAY return either 204 (no content) or 200 (OK).
A successful PUT which creates a new resource MUST return the URL of the
resource in the Location header.
A Client MUST specify a cache-conditional header on any write (PUT,
DELETE) operation (see here).
Failure to do so results in a bad request status code.
When comparing cache-conditional headers on GET or HEAD and the resource
has not changed then 304 is returned, if the cache-conditional headers do
not match any resource then 412 (pre-condition failed) is returned.
When comparing cache-conditional headers on PUT or DELETE and the
resource has not changed the resource is updated, if the cache-conditional
headers are stale a 409 (conflict) is returned. If the cache-conditional
headers do not match any resource then 412 (pre-condition failed) is
returned.
To successfully create a resource the cache-conditional header
"If-None-Match: *" will succeed.
Connection to Collection Storage
If a client performs a PUT method where the content-type is
"application/atom+xml" and the resource representation is a valid Atom feed
document with no entries then the server will create a new collection at the
specified URL. For more details see the collection storage specification.
HTTP Headers
The following headers are defined by the HTTP 1.1
specification, some are required to be supported by an Open Services for
Lifecycle Collaboration provider.
Direction
Mandatory
Name
Comments
Request
On PUT
Content-Type
Used on PUT to signify the content-type of the resource to create.
This value must be stored by the server.
Request
No
Accepts
May be used by the server to identify whether the client can consume
a resource, should not be used to content negotiation.
Request
If-Match, If-None-Match
Used to perform conditional requests, using ETags.
Request
If-Modified-Since, If-Unmodified-Since
Used to perform conditional requests, using Last-Modified dates.
Jazz.net Homepage
