Client Repository Communication API

Client <--> Repository Communication API

A Client can do more than just download the list of available applications from a given PND repository, So long as that repository provides the correct API interface.

All data is sent to the server via POST apart from when downloading an application which uses URL Parameters via GET All data is returned to the client in the JSON format.

The current API consists of the following:

API Key

A security md5 hash which would be generated for the user by the PND repository upon request, this would then be entered by the user and stored by the users client of choice. This has the benefit of not requiring the user to enter his/her password into the client or transfer it via HTTP_POST (this is mainly for convenience but is also more secure).

Handshake

Before any action can be carried out by the server Cyrptographic Authentication using nonce in a similar way to Digest Access Authentication is performed to make sure these requests are authenticated.

//---------> through POST method client sends request for handshake by POST param stage=1

//<--------- the client generates a new session (which lasts only 15 seconds), generates a
random 12 digit nonce sequance and returns this value to the client.

//---------> once the client has this nonce it generates its own client nonce and POSTs
this back to the server along with the username of the user and a special md5 hash
which works like this md5(NONCE+CNONCE+APIKEY). So the following gets posted
back to the server:
stage=2&user=<username>&hash=md5(NONCE+CNONCE+APIKEY)

//<--------- as long as the session on the server is still active, the server pulls up the
users APIKEY from the db and replicates the client submitted HASH for validation i.e.
md5(NONCE+CNONCE+APIKEY), the server then checks both hashes against each
other (client hash and server hash) and if they match we allow an action, after which
the session is destroyed again.

//if there are any errors in the POST or missing required params the session is
destroyed and the handshake needs to start again.

handling errors or success

Here is an example of how an error would be reported to the client.

{"error":{"number": 1,"text":"Handshake stage not supplied."}}

And here is an example of how success would be reported

{"success":{"number": 1,"text":"Request your action."}}

These parameters should be transferred in the URL via the POST method

Server Sessions

when starting a handshake the server will create a session from which it can store data such as the username and access token for the duration of the client/Repository interaction. If at any point the handshake fails or once the request has been completed, the session is destroyed, any further actions will require a fresh handshake. A session may only last 15 seconds after a successful handshake meaning if no action is requested within those 15 seconds the session is destroyed and again any further actions will require a fresh handshake.

Rating Submission

After a successful handshake 2 parameters will need to be POSTED to the appropriate server API URL which contains the rating (parameter "r") and the application id (parameter "id"). The "r" (rating) parameter can be a string of up to 300 characters. the "id" (application id) parameter should be the ID of the application we are assigning the comment to.

These parameters should be transferred via the POST method

Comment Submission

After a successful handshake 2 parameters will need to be POSTED to the appropriate server API URL which contains the comment (parameter "c") and the application id (parameter "id"). The "c" (comment) parameter can only be a number between 1 and 5. the "id" (application id) parameter should be the ID of the application we are assigning the rating to.

These parameters should be transferred via the POST method

Download logging / Purchased App Download

If you would like your chosen Repository to keep a list of your downloaded applications (this is not a list of what's installed on your SD card but a list of all the applications you ever downloaded) and or would like to download a purchased application via your chosen client, you will need to submit and extra param called "a" to the download URL. The "id" (application id) parameter should be the ID of the application you wish to download. The "a" (anonymous) parameter should be sent with the string value of "false" if you wish to authorise download log or purchased download.

These parameters should be transferred in the URL via the GET method

History of Downloads

If you would like to view all your logged downloads, after a successful handshake No parameters need to be sent. The client will return the list of applications in this format.

//History file. (type: json-object)
//
//Will use the JSON common-denominator encoding (can be read as ASCII, ISO-8859-1 or UTF-8)
//Unicode characters are escaped with "\uXXXX" as per the JSON standard.
{
  //Information about the users download history. (type: json-object)
  "history":{
    //Username of user(type: json-string)
    "user":"milkshake",
    //Information about the PND packages downloaded. (type: json-array)
    "packages":[
      {
        //The package's queryable id. (type: json-string, see PXML standard)
        "id":"sd-install-2011-03-10",
        //OPTIONAL: The Package version at the time of download. (type: json-object)
        "version":{
          "major":"1",    //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
          "minor":"6",    //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
          "release":"1",  //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
          "build":"1",    //(type: json-string, with characters 0-9, a-z, A-Z, +, -)
          "type":"release"//(type: json-string, "alpha", "beta", or "release")
        },
        //OPTIONAL: The Unix time at which the PND was downloaded. (type: int)
        "download_date":1335105932
      }
    ]
  }
}

see other proposals