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.

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, 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": "[email protected]",
    "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.

[TODO] Encoding JSON in headers for upload and download-style routes.