1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
****************
Network Protocol
****************
While Stone does not standardize the network protocol used to send messages
between hosts, we do anticipate that HTTP will be a popular medium. This
document describes how serialized Stone objects can be transmitted using
HTTP based on experiences from implementing the Dropbox v2 API.
Remote Procedure Calls
======================
The majority of the routes in the Dropbox API are expected to be used by
non-browser clients. Clients tend to be one of the several SDKs that Dropbox
maintains for popular programming languages.
Because of this, it was convenient to use the body of the HTTP request and
response to store JSON-serialized Stone objects. Both requests and responses
set the ``Content-Type`` header to ``application/json``.
Based on the ``get_account`` route defined in the running example in the `Language
Reference <lang_ref.rst>`_, the following is a sample exchange between a client
and server.
An example request::
POST /users/get_account
Content-Type: application/json
{
"account_id": "id-48sa2f0"
}
An example sucessful response::
200 OK
Content-Type: application/json
{
"account_id": "id-48sa2f0",
"email": "alex@example.org",
"name": "Alexander the Great"
}
An example error response::
409 Conflict
Content-Type: application/json
{
"reason": "no_account",
}
HTTP Endpoint
The ``get_account`` route defined in the ``users`` namespace was mapped to
the url ``/users/get_account``. No host information is shown intentionally.
HTTP Status Code
A response indicates that its body contains an object conforming to a
route's error data type by returning an HTTP 409 error code. It was
important to use a "protocol layer" feature to indicate if an error had
occurred.
Authentication
There is no authentication scheme shown in the above example. One
possibility is to use an ``Authorization`` header.
Browser Compatibility
=====================
[TODO] Encoding JSON in headers for upload and download-style routes.
|
