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.

Architecture Management Resource REST API

1.0 SPECIFICATION DRAFT

Introduction

In general a model in the architecture management space is stored across many resources. Each resource (i.e. element in a model) may have its own URI. This document specifies the behavior of the Service Provider when a client performs HTTP operations on the URI.

GET {AMR URI}

If the resource exists and the user has the priivledges to receive the resource, the return SHOULD be some representation of the entity represented by the URI. The exact format of the return contents depends on the Accept header and the ability of the service to provide the information in that form. Typically the return will be the OSLC Resource document, the actual raw contents of the resource, or a redirection to the web interface for rendering/viewing the resource. If more than one header is specified the service will decide which to format to return.

Accept Header Description of return format
application/rdf+xml The OSLC resource description document. The returned document contains meta information about the resource as defined in the AM Resource Definition.
application/xhtml+xml A document formatted for viewing with a browser using W3C XHTML 1.1 or a 302 redirection to another URL that does provide this document.
text/html A document formatted for viewing with a browser using W3C HTML 4 or a 302 redirect to another URL that does provide it.

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

Status Code Response Content Response Headers Description
200 OK {dependent on request's Accept header} ETag: {the current ETag value for this resource}
Content-Type: {the content type of the response}
The request was sucessful and the server has delivered the requested content in the format requested. If the Accept header specified application/rdf+xml then the OSLC resource format is returned. If an html accept type is specified the provider may return a valid html/xhtml resource.
302 Found (Redirect) none Location: {Resource Web URI} The model element URI for the desired format exists and is available at the supplied URI (Location header).
404 Not Found Error message   The request URI does not represent resource on the server

Service providers MAY support resource paging.

Service providers MAY support selective properties. Providers that do not support selective properties MUST respond with a 400 response and an appropriately worded error message.

Example

Request

GET https://liz:9443/resources/gcp_123

Response

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dc="http://purl.org/dc/terms/">

    <rdf:Description rdf:about="https://liz:9443/resources/gcp_123">

        <dc:title>ServiceInterface</dc:title>
        <rdf:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML#Interface"/>
        <dc:source rdf:resource="https://liz:9443/resources/gcp_123?source"/>
        <dc:description>
            Provides an service. This text may come from the model element's documentation properties.
        </dc:description>
        <dc:creator rdf:resource="https://liz:9443/users/adam"/>
        <dc:created rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime"> 2008-09-16T08:42:11.265Z</dc:created>
        <dc:contributor rdf:resource="https://liz:9443/users/dan"/>
        <dc:modified rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime"> 2008-12-16T10:12:00.000Z</dc:modified>
        <acme:accountCode>CUST123</acme:accountCode>
        <acme:elaborates rdf:resource="https://req.acme.com/reqs/req1"/>
        <dc:license rdf:resource="http://open-services.net/html/Terms.html"/>

    </rdf:Description>
</rdf:RDF> 

POST {AMR 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.

PUT {AMR URI}

Update the referenced resource with the request's body. Depending on the Content Type header the Service Provider MAY support the update of the 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, given the specified Content Type. If the Service Provider supports the update of the model 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:

Status Code Response Content Response Headers Description
200 OK updated AM resource's raw content Location: {AMR URI}
ETag: updated ETag
Once the AM resource is updated, the resulting resource representation is returned, and any server modified values are included.
400 Bad Request Error message   This response can be returned when any of the parameters are not properly structured. Some conditions when this can happen include: specification of query parameters or malformed content (malformed XML).
404 Not Found Error message   The request URI does not represent a resource on the server
412 Precondition Failed Error message   The ETag supplied in the If-Match request header value did not match that of the resource being modified.
410 Gone Error message   The request URI did exist at one time, however it has since been deleted.

Updating an AM resource involves replacing the current value with the entire supplied value.

DELETE {AMR URI}

Delete the AM resource represented by the given URL. Service providers MAY support a DELETE request on AM Resources. Further GET requests on this resource SHOULD result in a "410 Gone", a "404 Not Found" response or in the case of a ETag mismatch, 409 Conflict.

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

Status Code Response Content Response Headers Description
200 OK none   The service has marked the resource as deleted or physically has deleted the resource.
404 Not Found Error message   The request URI does not represent a resource on the server. The server does nothing.
410 Gone Error message   The request URI did exist at one time, however it has since been deleted. The server does nothing.
412 Precondition Failed Error message   The ETag supplied in the If-Match request header value did not match that of the resource being modified.
Topic revision: r18 - 20 Jul 2010 - 16:37:17 - JimConallen
 
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