From 2bed362f998b5d2cc706087f6ad7507acf7e8788 Mon Sep 17 00:00:00 2001
From: Moxie Marlinspike <moxie@thoughtcrime.org>
Date: Wed, 2 Apr 2014 12:07:09 -0700
Subject: [PATCH] Updated API Protocol (markdown)

---
 API-Protocol.md | 34 ++++++++++++++++++++++------------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/API-Protocol.md b/API-Protocol.md
index 0ccaa9a..20b5a84 100644
--- a/API-Protocol.md
+++ b/API-Protocol.md
@@ -217,15 +217,16 @@ Authorization: Basic {basic_auth}
 ## Submitting a message
 
 ```
-POST /v1/messages/
+PUT /v1/messages/{destination_number}
 Authorization Basic {basic_auth}
 
 {
+  relay: "{relay}",
   messages: [{
                type: {type},
-               destination: "{destination_number}",
+               destinationDeviceId: {destination_device_id},
+               destinationRegistrationId: {destination_registration_id},
                body: "{base64_encoded_message_body}", // Encrypted PushMessageContent
-               relay: "{relay}",
                timestamp: "{time_sent_millis_since_epoc}"
               },
              ...,
@@ -233,32 +234,41 @@ Authorization Basic {basic_auth}
 }
 ```
 
-1. `type` is the type of message. Supported types are enumerated below.
 1. `destination_number` is the PSTN number of the message recipient.
-1. `body` is the Base64 encoded (without padding) and encrypted `PushMessageContent` (above).
 1. `relay` (optional) is the relay the message recipient is registered with.
+1. `type` is the type of message. Supported types are enumerated below.
+1. `destination_device_id` is the target device the message corresponds to for the `destination_number`.
+1. `body` is the Base64 encoded (without padding) and encrypted `PushMessageContent` (above).
 1. `timestamp_sent_millis_since_epoch` is the timestamp of the message in millis since the epoch.
 
 **Returns**:
 
 1. `401` invalid authentication credentials.
+1. `409` mismatched devices.
+1. `410` stale devices.
 1. `413` rate limit exceeded.
 1. `415` badly formatted JSON.
-1. `200` request succeeded. The structure below is returned.
+1. `200` request succeeded.
+
+**409 Mismatched Devices**:
+
+This return code indicates that the devices in `messages` do not match the registered devices for `destination_number`.  The response body indicates the mismatch:
 
 ```
 {
-  "success" : [{destination_number}, {destination_number}, ..., {destination_number}],
-  "failure" : [{destination_number},...,{destination_number}]
+  missingDevices: [{missing_device_id}, {another_missing_device_id}, ...],
+  extraDevices: [{device_id_doesnt_exist}, ...]
 }
 ```
 
-Supported types:
+**410 Stale Devices**:
+
+This return code indicates that a target device has re-installed and the requesting client is sending a message for a stale session.  The response body indicates which devices are effected:
 
 ```
-int TYPE_MESSAGE_PLAINTEXT     = 0;
-int TYPE_MESSAGE_CIPHERTEXT    = 1;
-int TYPE_MESSAGE_PREKEY_BUNDLE = 3;
+{
+  staleDevices: [{stale_device_id}, ...]
+}
 ```
 
 ## Receiving a message