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

2,754 bytes added ,  12 July 2010
m
moved Labs/Weave/0.3/API to Services/Sync/Server/Archived/0.3/API
No edit summary
 
(67 intermediate revisions by 5 users not shown)
Line 9: Line 9:
| style="background-color: #efefef;" | '''Parameter'''
| style="background-color: #efefef;" | '''Parameter'''
| style="background-color: #efefef; width: 100px" | '''Default'''  
| style="background-color: #efefef; width: 100px" | '''Default'''  
| '''Max'''
| '''Description'''
| '''Description'''
|- valign="top"
| type
| required
| The type of object contained in the WBO payload. Each type has a defined structure associated with it, beginning with "object". Valid object subtypes, if used, are "cryptowrapper" (whch should be used for all WBOs that have an encrypted payload) or the object type as defined in the payload (optional). Types are hierarchical arrays, beginning with the "object" type.
|- valign="top"
|- valign="top"
| id
| id
| required
| required
| 64
| An identifying string. For a user, the id must be unique for a WBO within a collection, though objects in different collections may have the same ID.
| An identifying string. For a user, the id must be unique for a WBO within a collection, though objects in different collections may have the same ID.
|- valign="top"
|- valign="top"
| parent
| parentid
| none
| none
| 64
| The id of a parent object in the same collection. This allows for the creation of hierarchical structures (such as folders).
| The id of a parent object in the same collection. This allows for the creation of hierarchical structures (such as folders).
|- valign="top"
|- valign="top"
| modified
| modified
| time submitted
| time submitted
| The last-modified date, in Julian date format.
| float (2 decimal places)
| 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"
| sortindex
| none
| integer
| A sort index to allow for ordered lists/trees.
|- valign="top"
|- valign="top"
| encryption
| depth
| none
| none
| 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.
| tinyint
| The depth of the node from the root of the tree. Useful as a sort key for ordered trees.
|- valign="top"
|- valign="top"
| encoding
| payload
| utf-8
| none
| The character set of the decrypted payload.
| 256K
payload (required) - 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]
|}
|}


== Sample: ==
Weave Basic Objects and all data passed into the Weave Server should be utf-8 encoded.
 
=== Sample: ===
<pre>
<pre>
{
{
"type": ["object", "cryptowrapper"],
"id": "B1549145-55CB-4A6B-9526-70D370821BB5",
"id": "B1549145-55CB-4A6B-9526-70D370821BB5",
"parent": "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 =
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.
== GET ==
'''https://''server''/0.3/user/''username''/ '''
Returns a list of collections associated with the account
'''https://''server''/0.3/user/''username''/''collection'' '''
Returns a list of the WBO ids contained in a collection. This request has additional optional parameters:
{| width="100%" cellpadding="3"
{| width="100%" cellpadding="3"
|- style="background-color: #efefef;"
|- style="background-color: #efefef;"
Line 56: Line 80:
| '''Description'''  
| '''Description'''  
|- valign="top"
|- valign="top"
| server
| parentid
| The name of the Weave server.
| Returns the ids for objects in the collection that are the children of the parent id given.
|- valign="top"
|- valign="top"
| prefix
| older
| Any added path prefix that defines the Weave namespace on that server.
| Returns only ids for objects in the collection that have been last modified before the date given.
|- valign="top"
|- valign="top"
| version
| newer
| The Weave API version.
| Returns only ids for objects in the collection that have been last modified since the date given.
|- valign="top"
|- valign="top"
| user
| full
| The userid of the Weave user.
| If defined, returns the full WBO, rather than just the id.
|- valign="top"
|- valign="top"
| collection
| limit
| 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.
| Sets the maximum number of ids that will be returned.
|- valign="top"
|- valign="top"
| id
| offset
| The Weave Basic Object id.
| Skips the first n ids. For use with the limit parameter (required) to paginate through a result set.
|- valign="top"
|- valign="top"
| timestamp
| sort
| A Julian date.
| '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)
|}
|}


A WBO will always be accessible at the following URL. All URLs will have REST semantics:


https://''server''/''prefix''/''version''/''user''/''collection''/''id''
'''https://''server''/0.3/user/''username''/''collection''/''id'' '''
 
Returns the WBO in the collection corresponding to the requested id
 
== PUT ==
 
'''https://''server''/0.3/user/''username''/''collection''/''id'' '''
 
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.
 
The server will return the timestamp associated with the modification.
 
== POST ==
 
'''https://''server''/0.3/user/''username''/''collection'' '''
 
Takes an array of WBOs in the request body and iterates over them, effectively doing a series of atomic PUTs with the same timestamp.
 
Returns a hash of successful and unsuccessful saves, including guidance as to possible errors:
 
<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>
 
== DELETE ==
 
'''https://''server''/0.3/user/''username''/''collection'' '''
 
Deletes the collection and all contents. Additional request parameters may modify the selection of which items to delete:
 
{| width="100%" cellpadding="3"
|- style="background-color: #efefef;"
| '''Term'''
| '''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"
| offset
| Skips the first n objects in the defined set. Must be used with the limit parameter.
|- 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)
|}
 


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


Other URLs will allow for structured access. All these support the 'start' and 'limit' parameters to allow for pagination:
Deletes the WBO at the location given


https://''server''/''prefix''/''version''/''user''/''collection''
All delete requests return the timestamp of the action.


'''GET''': Returns a list of ids associated with the collection.
= X-If-Unmodified-Since =
<br>'''PUT''': Takes an array of WBOs and adds/updates them within the collection. Identical to looping over a series of /id urls.
<br>'''DELETE''': Deletes all objects in this collection.


https://''server''/''prefix''/''version''/''user''/''collection''/parent/''id''
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.


'''GET''': Returns a list of ids that are children of the specified id.
<br>'''PUT''': No applicable function.
<br>'''DELETE''': Deletes the object in the collection with this ID and all of its children.


https://''server''/''prefix''/''version''/''user''/''collection''/since/''timestamp''
= X-Weave-Alert =


'''GET''': Returns a list of ids modified within the collection since the timestamp given.  
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.
<br>'''PUT''': No applicable function.
<br>'''DELETE''': No applicable function.
http://server/prefix/version/user/collection/since/timestamp
Mconnor
Confirmed users, Bureaucrats and Sysops emeriti
812

edits

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