DAS/2 TOC $Id: das2_put.html,v 1.19 2006/04/26 15:35:13 dalke Exp $

PUT Requests on DAS/2 Genome URLs

This document describes the DAS/2 support for writebacks.

Introduction

DAS/2 supports writeback to the database. It allows for concurrent access to the database via a locking system, access control and authentication of users via HTTP authentication, and encryption of data via SSL.

The following operations are supported:

Create a new object.
The client makes a POST request on a DAS/2 feature/, type/ or property/ URL. The body of the POST is an XML document describing the object(s) and using placeholder IDs. In its response, the server returns a document describing the placeholder ID, a status code indicating the success or failure of the operation, and a permanent database ID if the operation was successful.

REQUEST:

POST http://www.wormbase.org/das/genome/volvox/1/feature/ 
Content-Type: text/x-das-sources+xml

      
      <?xml version="1.0" standalone="no"?>
      <!DOCTYPE DAS2FEATURE SYSTEM "http://www.biodas.org/dtd/das2feature.dtd">
      <FEATURELIST
          xmlns="http://www.biodas.org/ns/das/genome/2.00"
          xmlns:das="http://www.biodas.org/ns/das/properties/2.00"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:base="http://www.wormbase.org/das/genome/volvox/1/feature">
         <FEATURE   id = "exon1"
                     type = "type/curated_exon"
                   parent = "feature/gene_g000029" >
             <LOC  pos = "region/Chr3/1271:1507:1" /> 
             <PROP  ptype = "/property/genefinder-score">23</PROP>
             <PROP  ptype = "das:phase">0</PROP>
         </FEATURE>
         <FEATURE   id = "exon2"
                     type = "type/curated_exon"
                   parent = "feature/gene_g000029" >
             <LOC  pos = "region/Chr3/2003:2090:1" /> 
             <PROP  ptype = "/property/genefinder-score">10</PROP>
             <PROP  ptype = "das:phase">1</PROP>
         </FEATURE>
      </FEATURELIST>
If successful, this creates two new exons in the database. Their permanent IDs will be returned in the response.
Update an object, replacing its contents.
The client makes a PUT request on a DAS/2 URL that currently corresponds to a database object. The body of the PUT request replaces the contents of the existing object.

REQUEST:

PUT http://www.wormbase.org/das/genome/volvox/1/feature/exon_e000323 
Content-Type: text/x-das-sources+xml

      
      <?xml version="1.0" standalone="no"?>
      <!DOCTYPE DAS2FEATURE SYSTEM "http://www.biodas.org/dtd/das2feature.dtd">
      <FEATURELIST
          xmlns="http://www.biodas.org/ns/das/genome/2.00"
          xmlns:das="http://www.biodas.org/ns/das/properties/2.00"
          xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:base="http://www.wormbase.org/das/genome/volvox/1/">
         <FEATURE   id = "feature/exon_e000323"
                     type = "type/curated_exon"
                   parent = "feature/gene_g000029" >
             <LOC  pos = "region/Chr3/1272:1507:1" /> 
             <PROP  ptype = "das:phase">1</PROP>
         </FEATURE>
      </FEATURELIST>

This transaction replaces whatever was recorded about the indicated feature with the information given in the request body.

Update an object by adding to its contents
The client makes a POST request on a DAS/2 URL that currently corresponds to a database object. The contents of the POST request add new fields to the existing object.

REQUEST:

POST http://www.wormbase.org/das/genome/volvox/1/feature/exon_e000323 
Content-Type: text/x-das-sources+xml

      
      <?xml version="1.0" standalone="no"?>
      <!DOCTYPE DAS2FEATURE SYSTEM "http://www.biodas.org/dtd/das2feature.dtd">
      <FEATURELIST
          xmlns="http://www.biodas.org/ns/das/genome/2.00"
          xmlns:das="http://www.biodas.org/ns/das/properties/2.00"
          xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:base="http://www.wormbase.org/das/genome/volvox/1/">
         <FEATURE id = "feature/exon_e000323" >
                   <PROP  ptype = "/property/genefinder-score">23</PROP>
         </FEATURE>
      </FEATURELIST>

This transaction has added the "genefinder-score" property to the feature.

Delete an object
The client makes a DELETE request on a DAS/2 URL that corresponds to a database object. The object is deleted.

REQUEST:

DELETE http://www.wormbase.org/das/genome/volvox/1/feature/exon_e000323 
      (no content)

exon_e000323 is deleted from the feature space. Note that the server must ensure that all cross references to exon_e000323 are also deleted.

Obtaining a lock on a portion of the database
The client uses the POST request to create one or more objects of type text/x-das-lock+xml.

REQUEST:

POST http://www.wormbase.org/das/genome/volvox/1/lock/ 
Content-Type: text/x-das-sources+xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE LOCKS SYSTEM "http://www.biodas.org/dtd/das2lock.dtd">
<LOCKS
   xmlns="http://www.biodas.org/ns/das/genome/2.00"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xmlns:das="http://www.biodas.org/ns/das/genome/2.00"
   xml:base="http://www.wormbase.org/das/genome/volvox/1/">
    <LOCK          id="mylock1"
          filter_href="feature?overlaps=Chr3/1000:500000"
              expires="2005-04-25T12:50:18+00:00"
     />
 </LOCKS>

If successful, this transaction creates a single time-limited lock object spanning the region 1000 to 500000 bp on Chr3. If the request fails the reply shows why the request failed. In the case where the region (or part thereof) is already locked by another user, the reply will give the name of the user and the time their lock will expire.

During the lifetime of this lock a client will need to provide the ID of the lock object in order to modify any feature that lies within this range. Variants of this request can be used to abandon the lock, renew it, or extend it.

Creating New Objects

The protocol currently allows features, types and properties to be written back to the database. Sequences and assemblies are currently not supported since altering a sequence or assembly has the potential to invalidate a whole series of features.

In principle the procedure is simple. The client POSTs to the namespace of interest, one of .../type/, .../property, or .../feature, using XML that describes the object(s) to be created. Where the object's ID (URL) would ordinarily be located, the client uses a temporary placeholder ID that has no meaning outside the current transaction. This temporary ID is important in multiple updates because it provides a key by which the client can match the returned permanent IDs to the features that it has created. To make this possible the server returns a status document indicating the outcome of the request, and if successful, the temporary ID(S) with the matching permanent ID(s) that describe the newly-created objects.

New features

The client POSTs to http://<database-info>/feature/ using a request body of MIME type text/x-das-feature+xml. The body contains one or more features using the format described in GET Requests on DAS/2 URLs. Instead of using a public ID for the <FEATURE> id attribute, the client uses a temporary placeholder ID, which can be any series of alphanumeric characters. An example of this was given in the introduction to this document.

Locking: If the server supports locking, it will be necessary to add one or more lock= parameters to the end of the POST URL, as in: 

POST http://dev.wormbase.org/das/genome/volvox/1/feature/?lock=xyzzy

This is described in more detail in Locking.

New properties

The client POSTs to http://<database-info>/property/ using a request body of MIME type text/x-das-property+xml. The body contains one or more property descriptions using the format described in Retrieving Controlled Vocabularies of Property Types. Instead of using a public ID for the <PROPERTY> id attribute, the client uses a temporary placeholder ID, which can be any series of alphanumeric characters.

REQUEST:

POST http://dev.wormbase.org/das/genome/volvox/1/property/ 
Content-Type: text/x-das-sources+xml


<?xml version="1.0" standalone="no"?>
<!DOCTYPE DAS2PROPERTIES SYSTEM "http://www.biodas.org/dtd/das2properties.dtd">
<PROPERTY-LIST
   xmlns="http://www.biodas.org/ns/das/genome/2.00"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
   xml:base="http://dev.wormbase.org/das/genome/volvox/1/property/"
   >

   <PROPERTY id="SuperHMMScore" 
        ontology="http://www.wormbase.org/ontologies/feature-properties#SuperHMM"
	 xs:type="xs:integer"
      definition="The score emitted by SuperHMM version 2.0."
</PROPERTY-LIST>

The response to this will indicate that the temporary placeholder "SuperHMMScore" is replaced with a database-specific ID. Note that clients will use the globally unique ontology attribute to recognize this property as being the same even when it is represented by different local IDs among different databases.

Locking: If the server supports locking, it will be necessary to add one or more lock= parameters to the end of the POST URL, as in: 

POST http://dev.wormbase.org/das/genome/volvox/1/property/?lock=xyzzy

This is described in more detail in Locking.

New feature types

The client POSTs to http://<database-info>/type/ using a request body of MIME type text/x-das-featuretype+xml. The body contains one or more feature type descriptions using the format described in Fetching Information about Feature Types. Instead of using a public ID for the <TYPE> id attribute, the client uses a temporary placeholder ID, which can be any series of alphanumeric characters.

REQUEST:

POST http://dev.wormbase.org/das/genome/volvox/1/type/ 
Content-Type: text/x-das-sources+xml


<?xml version="1.0" standalone="no"?>
<!DOCTYPE DAS2TYPES SYSTEM "http://www.biodas.org/dtd/das2types.dtd">
<TYPES
     xmlns="http://www.biodas.org/ns/das/genome/2.00"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     xmlns:bg="http://www.bioperl.org/biographics/properties"
     xml:base="http://www.wormbase.org/das/genome/volvox/1/type/">
 <TYPE id="tRNAscan"
       ontology="http://song.sourceforge.net/ontologies/sofa#tRNA" 
         source="tRNAscan-SE-1.11"
  doc_href="http://www.wormbase.org/documentation/users_guide#tRNA"
       xml:base="tRNAscan/">
    <PROP id="bg:glyph"     value="box" />
    <PROP id="bg:bgcolor"   value="white" />
    <PROP id="bg:fgcolor"   value="black" />
 </TYPE>

The response to this will indicate that the temporary placeholder "tRNAscan" is replaced with a database-specific ID. However the globally unique sequence ontology attribute identifies this feature type as being the same even when it is represented with different local IDs in different databases.

Locking: If the server supports locking, it will be necessary to add an one or more lock= parameters to the end of the POST URL, as in: 

POST http://dev.wormbase.org/das/genome/volvox/1/type/?lock=xyzzy

This is described in more detail in Locking.

The New Feature Response

The response to a request to create new objects has a DAS/2 status code in the header indicating whether the request as a whole was accepted, and multiple status codes per in the body that indicate whether each requested object was successfully created. For successfully-created objects, the body maps the temporary object ID used in the request to the permanent object ID as represented in the database.

As described in The DAS Transaction, the HTTP header will contain an X-DAS-Status: line that describes the result of the request as a whole. A status of 200 indicates that the request was well-formed and that an attempt was made to create the object(s) in the database. Common failure codes are likely to include "501 Unimplemented feature," and "407 Access denied," which includes both insufficient authorization and lock problems.

The body of the document returned from the request contains the local and stable IDs of each objects, as well as object-by-object status information: 

Content-Type: text/x-das-sources+xml


<?xml version="1.0" standalone="no"?>
<!DOCTYPE DAS2UPDATELIST SYSTEM "http://www.biodas.org/dtd/das2updatelist.dtd">
<UPDATELIST
     xmlns="http://www.biodas.org/ns/das/genome/2.00"
     xml:base="http://dev.wormbase.org/das/genome/volvox/1/" >
 <UPDATE_STATUS localid="exon1" id="feature/E0000123" status="200" />
 <UPDATE_STATUS localid="exon2" id="feature/E0000124" status="200" />
 <UPDATE_STATUS localid="exon3" id="feature/E0000125" status="200" />
</UPDATELIST>

The returned object has MIME type text/x-das-updatelist+xml and XML DTD http://www.biodas.org/dtd/das2updatelist.dtd (currently a placeholder). The tags are:

<UPDATELIST>
This tag is a container for one or more <UPDATE_STATUS> tags, one for each of the new objects described in the original request.
<UPDATE_STATUS>
Each tag describes the outcome of the attempt to create an object. Required attributes are localid andstatus. The localid attribute gives the local ID for the feature, property or type, and status gives the status of the request, using one of the DAS/2 status codes. If successful (status code 200), an optional id tag gives the permanent ID of the created object. As usual, the full ID is obtained by resolving the value of the id attribute with the partial URL given by the xml:base attribute of the enclosing <UPDATELIST> tag. Successfully-created lock objects will also have the additional lock_expires attribute, as described under locking.

In the case of a writeback request that affects multiple objects, the database will not be modified unless all objects are sucessfully updated. In other words, the database should roll back to its prior state should an update error be encountered at any point during the process. The X-Das-Status HTTP header indicates whether the database was updated, and the response body contains object-by-object status information which indicates which object(s) caused problems. A lack of object status information in the response means that the updatability of the individual object is unknown, possibly because the transaction was aborted before the object could be evaluated.

Updating Objects

Existing objects in the database may be updated in either of two ways:

  1. The client may perform a PUT request on the URL identifier of the object to be updated. The body of the request replaces the object.
  2. The client may perform a POST request on the URL identifier of the object to be updated. The body of the request is appended to the object.

Updating Objects via PUT

Given the URL identifier of an existing object, the client creates a PUT request. The body of the PUT request is the appropriate XML representation of a feature, a featuretype, or a property.

REQUEST:

PUT http://www.wormbase.org/das/genome/volvox/1/feature/exon32 
Content-Type: text/x-das-sources+xml

      
      <?xml version="1.0" standalone="no"?>
      <!DOCTYPE DAS2FEATURE SYSTEM
      "http://www.biodas.org/dtd/das2feature.dtd">
      <FEATURELIST
          xmlns="http://www.biodas.org/ns/das/genome/2.00"
          xmlns:das="http://www.biodas.org/ns/das/properties/2.00"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:base="http://www.wormbase.org/das/genome/volvox/1/">
         <FEATURE id = "feature/exon32"
                     type = "type/curated_exon"
                   parent = "feature/gene_g000029" >
             <LOC pos = "region/Chr3/1271:1507:1" />
             <PROP ptype =
             "/property/genefinder-score">23</PROP>
             <PROP ptype = "das:phase">0</PROP>
         </FEATURE>
      </FEATURELIST>

The semantics of the PUT request is to completely replace the contents of the indicated object. Subfields of the object that are not mentioned in the PUT body are deleted. Note that the ID of the object to be updated is contained in two locations, the target of the PUT request and within the object itself. It is an error if these do not match.

On success, the server returns an X-Das-Status code of 200 and the feature is updated. The following error codes may occur:

403 Unknown object ID
The URL does not correspond to an existing object
404 Invalid object ID
The id attribute in the <FEATURE>, <PROPERTY>, or <TYPE> tag does not correspond to the ID indicated by the request URL.
406 No lock
Locking is required and you do not have a lock.
407 Access denied
Updating of this object is forbidden
Other
400 bad namespace; 405 region coordinate error; 500 server error; 501 unimplemented feature.

The body of an update response is a text/x-das-updatelist+xml document, which describes detailed outcomes for each of the PUT features. As in object creation, the database will be rolled back if any of the requested update operations fails.

The following examples illustrates feature types and properties.

Updating a feature type:

REQUEST:

PUT http://dev.wormbase.org/das/genome/volvox/1/type/tRNAscan 
Content-Type: text/x-das-sources+xml


<?xml version="1.0" standalone="no"?>
<!DOCTYPE DAS2TYPES SYSTEM "http://www.biodas.org/dtd/das2types.dtd">
<TYPES
     xmlns="http://www.biodas.org/ns/das/genome/2.00"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     xmlns:bg="http://www.bioperl.org/biographics/properties"
     xml:base="http://www.wormbase.org/das/genome/volvox/1/type/">
 <TYPE id="tRNAscan"
       ontology="http://song.sourceforge.net/ontologies/sofa#tRNA" 
         source="tRNAscan-SE-1.11"
  doc_href="http://www.wormbase.org/documentation/users_guide#tRNA"
       xml:base="tRNAscan/">
    <PROP id="bg:glyph"     value="box" />
    <PROP id="bg:bgcolor"   value="white" />
    <PROP id="bg:fgcolor"   value="black" />
 </TYPE>
</TYPES>

Updating a property:

REQUEST:

PUT http://dev.wormbase.org/das/genome/volvox/1/property/SuperHMMScore 
Content-Type: text/x-das-sources+xml


<?xml version="1.0" standalone="no"?>
<!DOCTYPE DAS2PROPERTIES SYSTEM "http://www.biodas.org/dtd/das2properties.dtd">
<PROPERTY-LIST
   xmlns="http://www.biodas.org/ns/das/genome/2.00"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
   xml:base="http://dev.wormbase.org/das/genome/volvox/1/property/"
   >

   <PROPERTY id="SuperHMMScore" 
        ontology="http://www.wormbase.org/ontologies/feature-properties#SuperHMM"
	 xs:type="xs:integer"
      definition="The score emitted by SuperHMM version 2.0." />
</PROPERTY-LIST>

Updating Objects via POST

The POST version of the object update is an append operation in which the partial object given in the POST body is merged into the full object in the database. This is intended to be used to update a single field in the object or to add additional values to a multi-valued field.

Since many fields are potentially multi-valued (such as the <LOC> field), a URL parameter overwrite=[0|1] is used to select whether the fields given in the body should overwrite the existing fields or be appended to it. This example will illustrate the difference:

REQUEST:

POST http://www.wormbase.org/das/genome/volvox/1/feature/exon32?overwrite=1 
Content-Type: text/x-das-sources+xml

      
      <?xml version="1.0" standalone="no"?>
      <!DOCTYPE DAS2FEATURE SYSTEM
      "http://www.biodas.org/dtd/das2feature.dtd">
      <FEATURELIST
          xmlns="http://www.biodas.org/ns/das/genome/2.00"
          xmlns:das="http://www.biodas.org/ns/das/properties/2.00"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:base="http://www.wormbase.org/das/genome/volvox/1/">
         <FEATURE id="feature/exon32">
             <LOC pos = "region/Chr3/1271:1507:1" />
         </FEATURE>
      </FEATURELIST>

This request will update the <LOC> field of the indicated exon, replacing whatever was there before. Object tags and attributes that are not explicitly mentioned retain their original values.

REQUEST:

POST http://www.wormbase.org/das/genome/volvox/1/feature/exon32?overwrite=0 
Content-Type: text/x-das-sources+xml

      
      <?xml version="1.0" standalone="no"?>
      <!DOCTYPE DAS2FEATURE SYSTEM
      "http://www.biodas.org/dtd/das2feature.dtd">
      <FEATURELIST
          xmlns="http://www.biodas.org/ns/das/genome/2.00"
          xmlns:das="http://www.biodas.org/ns/das/properties/2.00"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xml:base="http://www.wormbase.org/das/genome/volvox/1/">
         <FEATURE id="feature/exon32">
             <LOC pos = "region/Chr3/1271:1507:1" />
         </FEATURE>
      </FEATURELIST>

This request will add a new <LOC> field of the indicated exon, thereby increasing the number of alternative locations by one. As before, object tags and attributes that are not explicitly mentioned retain their original values.

The X-Das-Status and body of a POST update request are the same as the PUT request previously described.

Locking

A DAS/2 server may support property-based locking of sets of objects, in which case the client is required to obtain a valid lock before creating new objects or updating existing ones. Locking is accomplished by creating one or more lock objects in one of the supported namespaces. The contents of the lock object indicate the scope of objects that the user is authorized to update. Once a lock object is created, it must be referenced whenever updating an object. The server compares the provided lock object to the updated objects and grants the update if the two are "compatible." (Compatibility rules are described in detail later in this section.)

Lock objects are distinguished from other objects by having a "expires" attribute. The value of this attribute indicates how long the lock is valid for. Additional lock-specific attributes indicate the credentialing information used for authenticating access to the lock.

Creating Locks

To create a lock the client sends a POST request to the /lock namespace. The POSTed object must be a document of type text/x-das-lock+xml, and will contain at least one <LOCK> section. Example:

REQUEST:

POST http://www.wormbase.org/das/genome/volvox/1/lock/ 
Content-Type: text/x-das-sources+xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE LOCKS SYSTEM "http://www.biodas.org/dtd/das2lock.dtd">
<LOCKS
     xmlns="http://www.biodas.org/ns/das/genome/2.00"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     xmlns:das="http://www.biodas.org/ns/das/genome/2.00"
     xml:base="http://www.wormbase.org/das/genome/volvox/1/">
 <LOCK id="lock/mylock1"
       filter_href="feature?overlaps=Chr3/1000:2000" 
       expires="2005-04-25T12:50:00+00:00" />
 <LOCK id="lock/mylock2"
       filter_href="feature?overlaps=Chr20/50000:60000" 
       expires="2005-04-25T12:50:00+00:00" />
</LOCKS>

This requests the creation of two lock objects, one of which applies to features contained within the region Chr3/1000:2000 and the other of which applies to features contained within the regio Chr20:50000:60000. Both locks are requested to persist until 12:50 UTCon April 25, 2005.

The response to this request is a text/x-das-updatelist+xml document, as described earlier. In addition to the attributes shown earlier, the <UPDATE_STATUS> tag will contain a lock_expires attribute indicating the lifetime of the lock. This may be more or less than what the request asked for. As in earlier examples, the local ID of the requested lock is replaced by a stable ID provided by the server:

RESPONSE:

Content-Type: text/x-das-sources+xml


<?xml version="1.0" standalone="no"?>
<!DOCTYPE DAS2UPDATELIST SYSTEM "http://www.biodas.org/dtd/das2updatelist.dtd">
<UPDATELIST
     xmlns="http://www.biodas.org/ns/das/genome/2.00"
     xml:base="http://dev.wormbase.org/das/genome/volvox/1/lock" >
 <UPDATE_STATUS localid="mylock1" id="lock00004" status="200" expires="2005-04-25T13:00:00+00:00" />
 <UPDATE_STATUS localid="mylock2" id="lock00005 status="200" expires="2005-04-25T13:00:00+00:00" />
</UPDATELIST>

The response in this example indicates that the two locks were granted and assigned stable ids of "http://www.wormbase.org/das/genome/volvox/1/feature/lock00004 and lock00005, respectively.

The value of the filter_href attribute determines the scope of the lock. It is a valid DAS/2 namespace, and, optionally, namespace filters, as described in Lock Scopes.

Retrieving Locks

DAS/2 implements a lock object that is used to control concurrent writeback access to the database. Locks are scoped to a versioned data source, are owned by a particular user (or client application), and have a limited lifetime. At any time there may be no, one, or multiple locks in a database.

To fetch a list of all locks in the current source, perform a GET on the versioned data source URL appended with "/lock":

text/x-das-lock+xml

REQUEST:

http://www.wormbase.org/das/genome/volvox/1/lock

RESPONSE:

Content-Type: text/x-das-lock+xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE LOCKS SYSTEM "http://www.biodas.org/dtd/das2lock.dtd">
<LOCKS
     xmlns="http://www.biodas.org/ns/das/genome/2.00"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     xmlns:das="http://www.biodas.org/ns/das/genome/2.00"
     xml:base="http://www.wormbase.org/das/genome/volvox/1/">
 <LOCK id="lock/lock000001"
       filter_href="feature?inside=Chr3/1000:2000" 
       expires="2005-04-25T12:39:53+00:00"
     auth_type="Basic"
  credentials="janderson" />
 <LOCK id="lock/lock000018"
       filter_href="feature?inside=Chr20/50000:60000" 
       expires="2005-04-25T12:50:18+00:00"
     auth_type="Basic"
  credentials="janderson" />
 <LOCK id="lock/lock00091"
       filter_href="property" 
       expires="2005-04-25T12:10:00+00:00"
     auth_type="Certificate"
  credentials="C=UK/SP=CA/L=Hinxton/O=Sanger Institute/CN=James Gilbert" />
</LOCKS>

The request for a list of locks returns a document of time text/x-das-lock+xml. This document's tags and attributes are as follows:

Get schema as: [RNC] [RNG] [DTD]
<LOCKS>
A set of <LOCK> tags.
xml:base – The xml:base of the tag should be set to the start of the /region namespace of the current data source.
<LOCK> (zero or more)
A lock object
id – the URL for the lock
filter_href (optional) – the filter for the lock This is a relative URI that gives locked namespace and (optionally) query filter: e.g. feature?overlaps=Chr3/1000:2000;type=exon,intron,splice_site
expires (optional) – a datetime that indicates when the lock object expires
auth_type (optional) – an HTTP authentication type indicating the kind of authentication in use when lock created
credentials (optional) – an HTTP credential indicating the credentials presented by the peer

Each <LOCK> section contains a unique lock ID (relative to the xml:base). The lock-expires attribute is a date time string that indicates when the lock will become invalid. After a lock expires it will eventually be removed from the database, although this garbage collection may take some time to occur.

The auth_type and credentials attributes provides information about who owns the lock and what type of authentication was used when the user created this lock. The authentication process is controlled at the HTTP level and is described in more detail in DAS2 Updates. Possible values for auth_type include:

auth_typecredentialsExample
Basic Username JAnderson
Digest Username JAnderson
Host IP Address 143.48.1.250
Certificate Client certificate distinguished name C=US/SP=MA/L=Boston/O=Capricorn Organization/OU=Sales/CN=James Anderson/Email=janderson@capricorn.com

The filter_href attribute, if present, limits the scope of the lock. In the absence of the attribute, the lock's scope extends to the entire versioned datasource, which means that only the owner of the lock can make changes while the lock is in effect. If this attribute is present, then it is interpreted as a partial URL corresponding to a DAS/2 namespace, and the scope of the lock is limited to that namespace. For feature objects, additional filter arguments can be used to restrict the scope of the lock further.

filter_hrefInterpretation
feature Lock all features
type Lock all feature types
property Lock all feature properties
feature?inside=Chr3/50000:60000 Lock all features Chr3 from 50,000 to 60,000.
feature?inside=Chr3/50000:60000,Chr4/100000:110000 Lock all features inside the two indicated regions.
feature?inside=Chr3/50000:60000;type=exon Lock all exon features inside the indicated region.

While the syntax allows arbitrary subsets of features to be locked, server implementations may not allow the full range of possibilities. In particular, a DAS/2 writeback server is only required to support a single inside filter, and is not required to support either type or property locks.

Information about a single lock can be obtained by requesting the lock namespace with the lock ID appended:

REQUEST:

http://www.wormbase.org/das/genome/volvox/1/lock/lock000018

This will retrieve a text/x-das-lock+xml document containing a single <LOCK> subsection.

Authentication

As described in GET Requestson DAS/2 URLs, authentication of users is handled at the HTTP level. This allows DAS/2 administrators to implement any combination of host, user or certificate-based authentication. If authentication is in use, the lock object will contain fields indicating the type of authentication in use and the credentials used for authentication. These values are for informational purposes only and cannot be altered at the client side. Possible values include:

lock-auth-typelock-credentialsExample
Basic Username JAnderson
Digest Username JAnderson
Host IP Address 143.48.1.250
Certificate Client certificate distinguished name C=US/SP=MA/L=Boston/O=Capricorn Organization/OU=Sales/CN=James Anderson/Email=janderson@capricorn.com

The server can readily retrieve these values from the runtime environment of the request.

Lock Scopes

When locking is in use, the client must append one or more lock IDs to the URI whenever creating or updating objects. The syntax is:

REQUEST:

PUT http://dev.wormbase.org/das/genome/volvox/1/feature/exon_e000323?lock=lock00004;lock=lock00005

Before committing the updated objects to the database, the server will check that the indicated lock objects are valid and that they allow the requested operation. Criteria for lock validity are:

  1. The lock has not expired.
  2. The credentials of the user making the current request match the credentials of the user who owns the lock.
  3. The requested operation affects the same namespace as the lock; e.g. if the lock object is in the /feature namespace, then it only allows operations updates to the /feature namespace.
  4. If the lock contains scope restrictions (described next), the requested operation is compatible with those restrictions.

If any of these criteria fail to be satisified, the create or update operation will fail.

By default, a lock object locks the entire namespace referred to in the lock_href attribute. For example, a lock whose lock_href attribute is on the "type" namespace (relative to the xml:base attribute), will lock all feature types, allowing only the lock owner to add, update or delete types. A lock without any lock_href attribute at all will lock the entire database.

Locks that are scoped to the feature namespace can accept filter arguments as described in The Feature Request. These arguments further restrict the scope across which the lock applies. In principle, any of the filter arguments are accepted. For example, the following lock_href would lock all features that overlap bases 1000-2000 of Chr3 and are of type exon, intron or splice_site: 

<LOCK id="lock23" lock_href="feature?overlaps=Chr3/1000:2000;type=exon,intron,splice_site" />

In practice, however, writeback servers are only required to implement the "inside" filter, which is sufficient for region-based locking: 

<LOCK id="lock23" lock_href="feature?inside=Chr3/1000:2000,Chr4/50000:60000" />

This lock applies to features completely contained within region 1000-2000 of Chr3, or 50000-60000 of Chr4.

When a inside region scope is in effect, the lock acts only on features that are entirely contained entirely within the indicated region (feature start >= region start and feature end <= region end). Features that are outside of this region or which are only partially contained within the region are considered unlocked, and an attempt to update them will fail. The following cases hold:

Creation of a new feature object
The boundaries of the feature object must be entirely contained within the locked region. In the case of a batch creation of multiple objects such as a feature and its subfeatures, each of the subfeatures must be contained within the region specified by one of the locks given in the lock= argument.
Deletion of an object
The existing boundaries of the object to be deleted must be entirely contained within the locked region.
Update of an object
The existing boundaries of the object must be entirely contained within the locked region. In the case of an update that changes the location of the object, the new coordinates must also be contained within one of the locked regions given by the lock argument.

A lock cannot be granted if there are conflicts with existing valid locks. In practice, this means that there can only be one property or type lock at any time, and that a feature lock will only be granted if none of its inside regions overlap with regions covered by existing feature locks. In particular, a whole-genome feature lock (one without the inside filter) will only be granted if there are no outstanding feature locks.

Querying Locks

Once a lock has been created, it may be queried using a GET requests. In this example, a client requests information about a previously allocated lock with id lock00004:

REQUEST:

GET http://www.wormbase.org/das/genome/volvox/1/lock/lock00004

RESPONSE:

Content-Type: text/x-das-sources+xml

      
<?xml version="1.0" standalone="no"?>
<!DOCTYPE LOCKS SYSTEM "http://www.biodas.org/dtd/das2lock.dtd">
<LOCKS
     xmlns="http://www.biodas.org/ns/das/genome/2.00"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     xmlns:das="http://www.biodas.org/ns/das/genome/2.00"
     xml:base="http://www.wormbase.org/das/genome/volvox/1/">
 <LOCK id="lock00004"
       basic="JAnderson"
       Host="143.48.1.250"
       expires="2005-04-25T12:50:00+00:00" />
</LOCKS>

When authentication is in use some servers may restrict querying of locks or restrict the information returned by the query.

After a lock has expired it can no longer be queried.

Updating Locks

Once a lock has been created, it may be updated or deleted using PUT, POST and DELETE requests as described earlier. Fields that can be changed include the lock-expires attribute (e.g. to make the lock persist longer) or nested tags contained within the object.

In this example, a client requests the extension of the existing lock's expiration date for an additional hour, and extends the lock so that applies to the region of Chr3 between 10000 and 60000:

REQUEST:

PUT http://www.wormbase.org/das/genome/volvox/1/lock/lock00004 
Content-Type: text/x-das-sources+xml

      
<?xml version="1.0" standalone="no"?>
<!DOCTYPE LOCKS SYSTEM "http://www.biodas.org/dtd/das2locks.dtd">
<FEATURELIST
    xmlns="http://www.biodas.org/ns/das/genome/2.00"
    xmlns:das="http://www.biodas.org/ns/das/properties/2.00"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xml:base="http://www.wormbase.org/das/genome/volvox/1/lock/">
  <FEATURE      id="lock00004"
         lock-expires="2006-04-25T1:00:00+00:00" />
            lock_href="feature?inside=Chr3/10000:60000" /> 
</FEATURELIST>

When authentication is in use a lock object can only be deleted or modified by the owner of the lock, as indicated by lock-credentials. A server implementation may, at its discretion, choose to implement a "superuser" who is allowed to delete or modify any lock on the system.

After a lock has expired it can no longer be updated. Instead, a new lock must be created.

Lincoln D. Stein, lstein@cshl.edu
Cold Spring Harbor Laboratory
$Log: das2_put.html,v $
Revision 1.19  2006/04/26 15:35:13  dalke
Removed old Relax-NG schemas.
updating spec pages.

Revision 1.5  2005/10/20 22:27:16  sac
* Moved the locking stuff from the get document to the put document.
  For read-only access, you shouldn't have to worring about locking mechanics.
* Tweaked text concerning feature formats.
* Other minor tweaks to get document:
  - Using consistent wording just before "tag and properties"
  sections.
  - Added 'MIME type:' just before 
 mime types.

Revision 1.4  2005/04/29 19:33:06  edgrif
Add description of how to use localid & id object identifiers.

Revision 1.3  2005/04/29 00:23:44  edgrif
add text for when lock request fails.

Revision 1.2  2005/04/28 19:04:47  edgrif
fix up put doc to be template + generated spec.

Revision 1.1  2005/04/27 20:12:13  edgrif
das2_put_template.html and xml example files to replace das_put.html

Revision 1.8  2005/04/26 20:45:49  lstein
completely reworked how locks are obtained and modified

Revision 1.7  2005/04/26 18:07:02  edgrif
add details for client write/update + various small corrections.

Revision 1.6  2005/04/25 22:14:32  lstein
Fixed a variety of typographical errors and ambiguities.

Revision 1.5  2005/04/25 21:45:07  lstein
expanded discussion of locking

Revision 1.4  2005/01/11 13:46:58  lstein
Described the PUT and POST requests for updating existing objects.

Revision 1.3  2005/01/10 13:11:02  lstein
a little more work on update document

Revision 1.2  2005/01/07 01:37:36  lstein
a little more work on writeback protocol

Revision 1.1  2004/12/12 17:39:58  lstein
began reorganization of html pages

Revision 1.7  2004/11/13 20:01:52  lstein
committed changes that allen things i forgot

Revision 1.6  2004/11/12 01:12:08  lstein
Folded in changes discussed during Hinxton meeting; need to work on writeback description now

Revision 1.5  2004/09/26 10:49:59  lstein
very minor changes to correct xemacs regexp overflow bug

Revision 1.4  2004/09/26 10:06:25  lstein
gene das cleaned up

Revision 1.3  2004/09/26 09:57:54  lstein
gene das explained

Revision 1.2  2004/09/24 11:41:43  lstein
minor typographical changes

Revision 1.1  2004/09/17 20:02:49  lstein
added htmlized version of das2 protocol