MozillaWiki

Services/Sync/Server/Archived/0.3/API: Difference between revisions

Page Discussion

Services/Sync/Server/Archived/0.3/API (view source)

Revision as of 03:05, 12 July 2010

117 bytes removed ,  12 July 2010
m
moved Labs/Weave/0.3/API to Services/Sync/Server/Archived/0.3/API
 
(39 intermediate revisions by 5 users not shown)
Line 24: Line 24:
| modified
| modified
| time submitted
| time submitted
| 16
| float (2 decimal places)
| The last-modified date, in Julian date format.
| The last-modified date, in seconds since 01/01/1970 (see [http://www.ecma-international.org/publications/standards/Ecma-262.htm ecma-262]). Set by the server.
|- valign="top"
|- valign="top"
| encryption
| sortindex
| none
| none
| 256
| integer
| The URL of a Weave Encryption Record (WER) that defines how the payload is encrypted. No URL means that the payload is being sent unencrypted.
| A sort index to allow for ordered lists/trees.
|- valign="top"
|- valign="top"
| encoding
| depth
| utf-8
| none
| 16
| tinyint
| The character set of the decrypted payload.
| The depth of the node from the root of the tree. Useful as a sort key for ordered trees.
|- valign="top"
|- valign="top"
| payload
| payload
| none
| none
| 256K
| 256K
| The (possibly encrypted) JSON structure encapsualting the data of the record. This structure is defined separately for each WBO type.
| A string containing a JSON structure encapsulating the data of the record. This structure is defined separately for each WBO type. Parts of the structure may be encrypted, in which case the structure should also specify a record for decryption. [https://wiki.mozilla.org/Labs/Weave/0.3/API/Payloads Payload Definitions]
|}
|}
Weave Basic Objects and all data passed into the Weave Server should be utf-8 encoded.


=== Sample: ===
=== Sample: ===
Line 49: Line 51:
"parentid": "88C3865F-05A6-4E5C-8867-0FAC9AE264FC",
"parentid": "88C3865F-05A6-4E5C-8867-0FAC9AE264FC",
"modified": "2454725.98283",
"modified": "2454725.98283",
"encrytpion": "http://server/prefix/version/user/crypto-meta/B1549145-55CB-4A6B-9526-70D370821BB5",
"encryption": "",
"encoding": "shift-JIS",
"encoding": "shift-JIS",
"payload": "a89sdmawo58aqlva.8vj2w9fmq2af8vamva98fgqamff..."
"payload": "{\"encryption\":\"http://server/prefix/version/user/crypto-meta/B1549145-55CB-4A6B-9526-70D370821BB5\", \"data\": \"a89sdmawo58aqlva.8vj2w9fmq2af8vamva98fgqamff...\"}"
}
}
</pre>
</pre>


= URL Semantics =
= URL Semantics =
{| width="100%" cellpadding="3"
|- style="background-color: #efefef;"
| '''Term'''
| '''Description'''
|- valign="top"
| server
| The name of the Weave server.
|- valign="top"
| prefix
| Any added path prefix that defines the Weave namespace on that server.
|- valign="top"
| version
| The Weave API version.
|- valign="top"
| user
| The userid of the Weave user.
|- valign="top"
| collection
| A defined grouping of objects into a set. All basic objects will be a member of one collection, and it will be the access point for those objects.
|- valign="top"
| id
| The Weave Basic Object id.
|}


A WBO will always be accessible at the following URL. All URLs will have REST semantics:  
Weave URLs follow, for the most part, REST semantics. Request and response bodies are all JSON-encoded.
 
Weave uses HTTP basic auth (over SSL, so as to maintain password security). If the auth username does not match the username in the path, the server will issue an [https://wiki.mozilla.org/Labs/Weave/0.3/ResponseCodes Error Response]
 
The Weave API has a set of  [https://wiki.mozilla.org/Labs/Weave/0.3/ResponseCodes Weave Response Codes] to cover errors in the request or on the server side. The format of a successful response is defined in the appropriate request method section.


'''https://''server''/''prefix''/''version''/''user''/''collection''/''id'' '''
== GET ==


'''GET''': Retrieve the object.
'''https://''server''/0.3/user/''username''/ '''
<br>'''PUT''': Add/update the object.
<br>'''DELETE''': Delete the object.


Batch processing can be done with:
Returns a list of collections associated with the account


'''https://''server''/''prefix''/''version''/''user''/''collection'' '''
'''https://''server''/0.3/user/''username''/''collection'' '''


'''GET''': Returns a list of ids associated with the collection.
Returns a list of the WBO ids contained in a collection. This request has additional optional parameters:
<br>'''POST''': Takes an array of WBOs and adds/updates them within the collection. Identical to doing a set of PUTs over /id urls.
<br>'''DELETE''': Deletes all objects in this collection.


Optional '''GET''' parameters:
{| width="100%" cellpadding="3"
{| width="100%" cellpadding="3"
|- style="background-color: #efefef;"
|- style="background-color: #efefef;"
Line 102: Line 80:
| '''Description'''  
| '''Description'''  
|- valign="top"
|- valign="top"
| wbo
| parentid
| The json objects/array of json objects to be POSTed
| Returns the ids for objects in the collection that are the children of the parent id given.
|- valign="top"
|- valign="top"
| parentid
| older
| Returns the objects in the collection that are the children of the parent id given.
| Returns only ids for objects in the collection that have been last modified before the date given.
|- valign="top"
|- valign="top"
| modified
| newer
| Returns only objects in the collection that have been modified since the date given, ordered by earliest timestamp.
| Returns only ids for objects in the collection that have been last modified since the date given.
|- valign="top"
|- valign="top"
| full
| full
| If defined, returns the full objects, rather than a group of ids.
| If defined, returns the full WBO, rather than just the id.
|- valign="top"
|- valign="top"
| limit
| limit
| Caps the number of objects that will be returned.
| Sets the maximum number of ids that will be returned.
|- valign="top"
|- valign="top"
| offset
| offset
| Skips the first n objects, for use with the limit parameter
| Skips the first n ids. For use with the limit parameter (required) to paginate through a result set.
|- valign="top"
| sort
| 'oldest' - Orders by modification date (oldest first)<br>
'newest' - Orders by modification date (newest first)<br>
'index' - Orders by the sortindex (ordered lists)<br>
'depthindex' - Orders by depth, then by sortindex (ordered trees)
|}
|}


= Response Codes =


'''200 OK''' -- Returned on a successful request. Note that this does not guarantee that the server has done anything - deleting a nonexistent object will return a 200.
'''https://''server''/0.3/user/''username''/''collection''/''id'' '''


'''400 Bad Request''' -- Will be returned if there was an error in the client's request, such as malformed JSON, a protocol/content mismatch or a missing required field. The response will contain json data that may provide hints as to the problem.
Returns the WBO in the collection corresponding to the requested id


'''401 Unauthorized''' -- Username and password do not allow access to the requested URL
== PUT ==


'''404 Not Found''' -- Returned if the user does not exist.
'''https://''server''/0.3/user/''username''/''collection''/''id'' '''


'''503 Service Unavailable''' -- An internal error (storage failure). Please try back again later.
Adds the WBO defined in the request body to the collection. If the WBO does not contain a payload, it will only update the provided metadata fields on an already defined object.


= Payloads =
The server will return the timestamp associated with the modification.


Payloads are a hash with a required "type" key that defines the object type of the payload. Other keys will be required based on this type.
== POST ==


Here are some defined Payload Structures:
'''https://''server''/0.3/user/''username''/''collection'' '''


== Bookmarks ==
Takes an array of WBOs in the request body and iterates over them, effectively doing a series of atomic PUTs with the same timestamp.


(needs defining)
Returns a hash of successful and unsuccessful saves, including guidance as to possible errors:


== History ==
<pre>
{"modified":1233702554.25,"success":["{GXS58IDC}12","{GXS58IDC}13","{GXS58IDC}15","{GXS58IDC}16","{GXS58IDC}18","{GXS58IDC}19"],"failed":{"{GXS58IDC}11":["invalid parentid"],"{GXS58IDC}14":["invalid parentid"],"{GXS58IDC}17":["invalid parentid"],"{GXS58IDC}20":["invalid parentid"]}}
</pre>


(needs defining)
== DELETE ==


== Private Key ==
'''https://''server''/0.3/user/''username''/''collection'' '''


Public Key payloads must be unencrypted. Note that the key itself is still passphrase protected.
Deletes the collection and all contents. Additional request parameters may modify the selection of which items to delete:


{| width="100%" cellpadding="3"
{| width="100%" cellpadding="3"
|- style="background-color: #efefef;"
|- style="background-color: #efefef;"
| style="background-color: #efefef;" | '''Parameter'''
| '''Term'''
| style="background-color: #efefef; width: 100px" | '''Default'''
| '''Description'''  
| '''Description'''
|- valign="top"
| parentid
| Only deletes objects in the collection that are the children of the parent id given.
|- valign="top"
| older
| Only deletes objects in the collection that have been last modified before the date given.
|- valign="top"
| newer
| Only deletes objects in the collection that have been last modified since the date given.
|- valign="top"
| limit
| Sets the maximum number of objects that will be deleted.
|- valign="top"
|- valign="top"
| key_data
| offset
| required
| Skips the first n objects in the defined set. Must be used with the limit parameter.
| The private key, passphrase encrypted.
|- valign="top"
|- valign="top"
| public_key
| sort
| required
| 'oldest' - Orders by modification date (oldest first)<br>
| The URI to the public key associated with this private key.
'newest' - Orders by modification date (newest first)<br>
'index' - Orders by the sortindex (ordered lists)<br>
'depthindex' - Orders by depth, then by sortindex (ordered trees)
|}
|}


=== Sample ===
<pre>
  "payload":
  {
    "type: "private_key",
    "key_data": "nviuwc023nd210o3idn120x283cm...",
    "public_key": "A24349145-5AB-2YX-9526"
  }
</pre>


'''https://''server''/0.3/user/''username''/''collection''/''id'' '''


== Public Key ==
Deletes the WBO at the location given


Public Key objects must be unencrypted.
All delete requests return the timestamp of the action.  


{| width="100%" cellpadding="3"
= X-If-Unmodified-Since =
|- style="background-color: #efefef;"
| style="background-color: #efefef;" | '''Parameter'''
| style="background-color: #efefef; width: 100px" | '''Default'''
| '''Description'''
|- valign="top"
| key_data
| required
| The public key
|- valign="top"
| private_key
| required
| The URI to the private key associated with this private key.
|}


=== Sample ===
On any write transaction (PUT, POST, DELETE), this header may be added to the request, set to a timestamp. If the collection to be acted on has been modified since the timestamp given, the request will fail.
<pre>  "payload":
  {
    "type: "public_key",
    "key_data": "nviuwc023nd210o3idn120x283cm...",
    "private_key": "B24349145-5AB-2YX-9526"
  }
</pre>


== Cryptometa ==


Cryptometa objects must be unencrypted.
= X-Weave-Alert =


{| width="100%" cellpadding="3"
This header may be sent back from any transaction, and contains potential warning messages, information, or other alerts. The contents are intended to be human-readable.
|- style="background-color: #efefef;"
| style="background-color: #efefef;" | '''Parameter'''
| style="background-color: #efefef; width: 100px" | '''Default'''
| '''Description'''
|- valign="top"
| algorithm
| required
| A hash, containing a "name" key and associated value, and any additional data required for the algorithm, such as "salt" or "iv".
|- valign="top"
| keyring
| empty
| A hash in which the keys are URLs to publickey WERs and the values are the encryption string used with that key to encrypt this record. The keys may be fully qualified URLs, or relative to the id level (thus, just the id is acceptable)
|}
 
=== Sample ===
<pre>
  "payload":
  {
    "type: "cryptometa",
    "algorithm":
    {
      "name": "aes-256-cbc",
      "salt": "234imasd9f8w23m7",
      "iv": "2w3kmv9821maz985"
    }
    "keyring":
    {
  "B24349145-5AB-2YX-9526": "m29f2mnvwiecvnw0ev...",
    }
  }
 
</pre>
Mconnor
Confirmed users, Bureaucrats and Sysops emeriti
812

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/112914...237537"