Network API Requests

These are the types of requests that may be made within the Network API. If you are looking for what version this api is at see Network API.

##Request Structure

{
   "request": "target-translation", -- the request type
   "uuid": "79ecb788-c22c-4991-9788-016eae6d6b2e", -- the unique id for this request
   "context": { } -- any optional data necessary to provide sufficient context for the request
}

The request field contains the type of request that should be fulfilled by the requestee. The uuid is a Universally Unique IDentifier based on RFC 4122. For Android implementations you may reference java.util.UUID.

When responding to a request the peer should always use the request type and uuid of the original request. Only the context may differ when responding to a request.

###What is a Request A request is uniquely identified by a request type and a uuid. A request may contain different context as it travels between peers. A request is considered complete once the request uuid has been discarded by all involved peers. For details on how a request is used on the wire see the Network API.

####Requests (two way) Normal requests involve two way communcation between devices. The receiving device is required to respond in same form as the request. In other words, when a request is sent to a peer the response is made with the same request type and uuid. Example

// here peer1 is initiating a request for a target translation from peer2
(request starts)
peer1 --> target-translation (please give me a target translation xx_xx_xx) --> peer2
peer1 <-- target-translation (here is the target translation) <-- peer2
(request ends)

####Alerts (one way) Alerts are one way messages from one device to another. The receiving device should not respond to the alert directly but may indirectly follow up with separate alert or request. Alerts are always prefixed with alert. Alerts are most often used when user input is required. For example once device may "alert" another device to the availability of a target translation for importing:

// here peer2 notifies peer1 that the target translation is available
(request starts)
peer1 <-- alert-target-translation (would you like the target translation xx_xx_xx?) <-- peer2
(request ends)
// user reads alert and asks for target translation
(request starts)
peer1 --> target-translation (please give me a target translation xx_xx_xx) --> peer2
peer1 <-- target-translation (here is the target translation) <-- peer2
(request ends)

Another example if the alert was ignored.

(request starts)
peer1 <-- alert-target-translation (would you like the target translation xx_xx_xx?) <-- peer2
(request ends)
// user reads request but ignores it

In each of the above examples there would be a unique uuid (as well as an optional context) in the request being sent back and forth between the peers. When the requests end their uuid has been discarded by all involved peers. Later, a new request may be made for offering/retrieving the same target translation, however this is a brand new request and will contain it's own unique uuid.

###Why do we need the UUID? The uuid allows peers on the network to maintain state about a request as it travels (possibly slowly) through the network. Some requests will be processed automatically by the app and others will require user interaction.

##alert-target-translation Used to notify a peer that the target translation is available.

// context
{
  "target_translation_id": "en-obs-text-obs",
  "package_version": 6, -- version of the target translation format
  "project_name": "Open Bible Stories",
  "target_language_name": "English",
  "progress": 0.45 -- this translation is 45% complete
}

##target-translation Used to request a target translation from a peer.

####Requesting

// context
{
  "target_translation_id": "en-obs-text-obs",
}

####Sending

// context
{
  "port": 9999, -- the port where the file can be downloaded
  "name": "en-obs-text-obs.tstudio", -- the file name
  "size": 1234 -- size of the file in bytes
}

##target-translation-list Used to offer/request a list of target translations from a peer.

####Requesting

// context
{
  "preferred_source_language_ids":[] -- an array of source language id's
}

####Sending

// context
TBD