Revision dfb28993

b/docs/source/devguide.rst
25 25 
=========================  ================================
26 26 
Revision                   Description
27 27 
=========================  ================================
28 
0.8 (Dec 19, 2011)         Update allowed versioning values.
28 
0.8 (Dec 22, 2011)         Update allowed versioning values.
29 29 
\                          Change policy/meta formatting in JSON/XML replies.
30 30 
\                          Document that all non-ASCII characters in headers should be URL-encoded.
31 31 
\                          Support metadata-based queries when listing objects at the container level.
32 32 
\                          Note Content-Type issue when using the internal django web server.
33 33 
\                          Add object UUID field.
34 
\                          Always reply with the MD5 in the ETag.
34 35 
0.7 (Nov 21, 2011)         Suggest upload/download methods using hashmaps.
35 36 
\                          Propose syncing algorithm.
36 37 
\                          Support cross-account object copy and move.
......
731 732 

  		





  732
  733
  
    
The reply is the object's data (or part of it), except if a hashmap is requested with ``hashmap``, or a version list with ``version=list`` (in both cases an extended reply format must be specified). Object headers (as in a ``HEAD`` request) are always included.


  		





  733
  734
  
    

  		





  734
  
  
    
Hashmaps expose the underlying storage format of the object. Note that each hash is computed after trimming trailing null bytes of the corresponding block.


  		





  
  735
  
    
Hashmaps expose the underlying storage format of the object. Note that each hash is computed after trimming trailing null bytes of the corresponding block. The ``X-Object-Hash`` header reports the single Merkle hash of the object's hashmap (refer to http://bittorrent.org/beps/bep_0030.html for more information).


  		





  735
  736
  
    

  		





  736
  737
  
    
Example ``format=json`` reply:


  		





  737
  738
  
    

  		





  ......




  846
  847
  
    
==========================  ===============================


  		





  847
  848
  
    
Reply Header Name           Value


  		





  848
  849
  
    
==========================  ===============================


  		





  849
  
  
    
ETag                        The MD5 hash of the object (on create)


  		





  
  850
  
    
ETag                        The MD5 hash of the object


  		





  850
  851
  
    
X-Object-Version            The object's new version


  		





  851
  852
  
    
==========================  ===============================


  		





  852
  853
  
    

  		





  ......




  958
  959
  
    

  		





  959
  960
  
    
Optionally, truncate the updated object to the desired length with the ``X-Object-Bytes`` header.


  		





  960
  961
  
    

  		





  961
  
  
    
A data update will trigger an ETag change. Updated ETags correspond to the single Merkle hash of the object's hashmap (refer to http://bittorrent.org/beps/bep_0030.html for more information).


  		





  
  962
  
    
A data update will trigger an ETag change. Updated ETags may happen asynchronously and appear at the server with a delay.


  		





  962
  963
  
    

  		





  963
  964
  
    
No reply content. No reply headers if only metadata is updated.


  		





  964
  965
  
    

  		





  ......




  1071
  1072
  
    
* The object's Merkle hash is always returned in the ``X-Object-Hash`` header.


  		





  1072
  1073
  
    
* The object's UUID is always returned in the ``X-Object-UUID`` header. The UUID remains unchanged, even when the object's data or metadata changes, or the object is moved to another path (is renamed). A new UUID is assigned when creating or copying an object.


  		





  1073
  1074
  
    
* Object create using ``POST`` to support standard HTML forms.


  		





  1074
  
  
    
* Partial object updates through ``POST``, using the ``Content-Length``, ``Content-Type``, ``Content-Range`` and ``Transfer-Encoding`` headers. Use another object's data to update with ``X-Source-Object`` and ``X-Source-Version``. Truncate with ``X-Object-Bytes``. New ETag corresponds to the Merkle hash of the object's hashmap.


  		





  
  1075
  
    
* Partial object updates through ``POST``, using the ``Content-Length``, ``Content-Type``, ``Content-Range`` and ``Transfer-Encoding`` headers. Use another object's data to update with ``X-Source-Object`` and ``X-Source-Version``. Truncate with ``X-Object-Bytes``.


  		





  1075
  1076
  
    
* Include new version identifier in replies for object replace/change requests.


  		





  1076
  1077
  
    
* Object ``MOVE`` support.


  		





  1077
  1078
  
    
* Conditional object create/update operations, using ``If-Match`` and ``If-None-Match`` headers.


  		





  ......




  1201
  1202
  
    

  		





  1202
  1203
  
    
Notes:


  		





  1203
  1204
  
    

  		





  1204
  
  
    
* States represent file hashes (either MD5 or Merkle). Deleted or non-existing files are assumed to have a magic hash (e.g. empty string).


  		





  
  1205
  
    
* States represent file hashes (it is suggested to use Merkle). Deleted or non-existing files are assumed to have a magic hash (e.g. empty string).


  		





  1205
  1206
  
    
* Updating a state (either local or remote) implies downloading, uploading or deleting the appropriate file.


  		





  1206
  1207
  
    

  		





  1207
  1208
  
    
Recommended Practices and Examples


  		












Also available in:
  Unified diff