Architecture Management Link Resource REST API

1.0 SPECIFICATION DRAFT

Introduction

Links are first class resources. Since they contain properties and specify a customizable type they are directly addressable and have a URI of their own. Some properties in links can be edited, but not all.

HEAD {Link Resource URI}

The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. The metainformation contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request.

This method can be used for obtaining metainformation about the entity implied by the request without transferring the entity-body itself. This method is often used for testing for existence, recent modification, or to obtain the most recent ETag value in preparation for a PUT or DELETE.

GET {Link Resource URI}

Returns the link resource identified by the URI given.

The service provider MUST support these media types for the response content body:

• application/x-oslc-am-link+xml
• application/xml
• text/xml

A server provider MAY return an ETag HTTP header in the response that can be included in HTTP PUT requests for concurrent modification validation.

A service provider MUST support at least the following HTTP response status codes:

Example

Request

GET http://example.com/links/fab328s9ed7ad
Accept: application/x-oslc-common-link+xml

Response

200 OK
ETag: "_3Z3mxMD_Ed6YkqfTZH8hGg"

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
   xmlns:oslc="http://open-services.net/xmlns/common/1.0/"
   xmlns:dc="http://purl.org/dc/terms/"
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   
   <oslc:Link rdf:about="http://example.com/links/fab328s9ed7ad">
      <rdf:subject rdf:resource="http://example.com/resources/amresource15"/>
      <rdf:object rdf:resource="http://example2.com/resources/workitem24"/>
      <rdf:predicate rdf:resource="http://example.com/types/models"/>
      <dc:description>This only models the behavior, not structure</dc:description>

      <dc:creator rdf:resource="http://example.com/users/developer1" />
      <dc:created rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">
         2009-10-20T19:49:47-04:00
      </dc:created>

      <dc:contributor rdf:resource="http://example.com/users/admin1" />
      <dc:modified rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">
         2009-10-20T19:49:47-04:00
      </dc:modified>

   </oslc:Link>
</rdf:RDF> 

PUT {Link URI}

Update the link properties with the request's body. Depending on the Content Type header the Service Provider MAY support the update of the link resource. If the Service Provider does not support the specified content type the Service Provider MUST return a 415 Unsupported Media Type response, and the response MUST include an Allow header containing a list of valid methods for the requested resource. If the Service Provider supports the update of the link resource the request body contains the entire resource to be replaced.

The request MUST include the current ETag value for the resource.

A service provider MUST support at least the following HTTP response status codes:

Example

Request

PUT http://example.com/links/fab328s9ed7ad
If-Match: "_3Z3mxMD_Ed6YkqfTZH8hGg"

Response

200 OK
ETag: "_3JsftbzAEd6rn5xqnZzGpQ"

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
   xmlns:oslc="http://open-services.net/xmlns/common/1.0/"
   xmlns:dc="http://purl.org/dc/terms/"
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   
   <oslc:Link rdf:about="http://example.com/links/fab328s9ed7ad">
      <rdf:subject rdf:resource="http://example.com/resources/amresource15"/>
      <rdf:object rdf:resource="http://example2.com/resources/workitem12"/>
      <rdf:predicate rdf:resource="http://example.com/types/documents"/>
   </oslc:Link>
</rdf:RDF> 

DELETE {Link Resource URI}

Delete the link resource represented by the given URL. Service providers MAY support a DELETE request on AM Link 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:

Example

Request

DELETE http://example.com/links/fab328s9ed7ad
If-Match: "_3JsftbzAEd6rn5xqnZzGpQ"
 

200 OK

POST {Link Resource URI}

Not supported. The Service Provider MUST return a 405 Method Not Allowed response. The response MUST include an Allow header containing a list of valid methods for the requested resource.

Back to Architecture Management REST API 1.0 Home

-- JimConallen - 01 Sep 2009