git.maemo.org Git - speedfreak/blob - documents/API.txt

   1 API specifications for client-server communication
   2 ==================================================
   3
   4
   5 General information
   6 ===================
   7
   8 This document will briefly describe API that is used in Speed Freak project.
   9 In this document client will be Maemo 5 application running on Nokia N900 device.
  10 Server will be PHP application running on api.speedfreak-app.com
  11
  12 General technical information
  13 =============================
  14
  15 XML will be used for encapsulating data sent to and received from server. XML will
  16 be sent using HTTP protocol as POST data. Once product is launched HTTP will be
  17 swapped in favor of HTTPS for additional security.
  18
  19 All requests sent to server should satisfy following requirements:
  20
  21 - Login and password supplied via HTTP basic authentication (not required for
  22 registration)
  23 - Post field xml should contain XML (not required in login request)
  24 - XML should be UTF8 encoded
  25
  26 Server in return will respond with XML in body of the response if request was
  27 successful or with HTTP error code if there was problem processing the request.
  28 Successful requests return 200 HTTP status code.
  29
  30 Here is the list of general errors that client might encounter:
  31
  32 - 404: Request sent to incorrect URL
  33 - 500: General error during processing request
  34 - 403: Client has no privileges to access this resource
  35 - 400: Invalid request
  36 - 401: Failed to authenticate
  37
  38 Registration process
  39 ====================
  40
  41 URL: /users/register
  42
  43 Every single client should register before it can send own measurement results or
  44 fetch other's results. During registration client has to supply following information:
  45
  46 - Login: This is 3-12 charecters long nickname that has to be unique
  47 - Password: 6-255 charectors long password
  48 - Email: email address that will be used for password recovery etc. Has to be unique.
  49 - Description: Additional information that user might want to supply.
  50
  51 Below is example of XML that client might send to server to register an account:
  52
  53 <?xml version="1.0" encoding="utf-8"?>
  54 <user>
  55     <login>test827</login>
  56     <password>thisisaveryinsecurepassword</password>
  57     <email>test@example.com</email>
  58     <description>My car is cool</description>
  59 </user>
  60
  61 If registration is successful server will return 200 HTTP status code along with
  62 text "OK" in the response body. In other cases (invalid email, login exists etc)
  63 server will return HTTP error code 400 with error message in the body text.
  64
  65 User can also supply avatar image as POST field named "avatar". Please notice that
  66 avatar image must not exceed 100 kilobytes in size and should be supplied in Jpeg format.
  67
  68 Login
  69 =====
  70
  71 URL: /users/login
  72
  73 Because communication with server has no state there is no need to login. Client
  74 might need to verify that credentials supplied by user are correct. In order to
  75 do that client can send a login request which will just verify that login and password
  76 are correct and user exists in database.
  77
  78 When making a login request you don't have to supply XML, only basic authentication.
  79 If credentials are correct server will return "OK" along with HTTP status code 200.
  80 In any other case it will return 401 HTTP error code along with error description.
  81
  82
  83 List all users
  84 ==============
  85
  86 URL: /users/list_all
  87
  88 Using this you can get XML containing all registered users. Last activity attribute shows date and time
  89 when user has contacted the server. Example output below:
  90
  91 <?xml version="1.0" encoding="utf-8"?>
  92 <users>
  93         <user login="test" description="<![CDATA my car rox! ]]>" last_activity="2010-05-13 21:47:15"  />
  94         <user login="test1" description="<![CDATA my car rox too! ]]>" last_activity="2010-05-13 21:28:00"  />
  95 </users>
  96
  97
  98 Viewing user's profile
  99 ======================
 100
 101 URL: /users/info/username
 102
 103 Username is in this case username of user who's information you want to retrieve. In return you will get XML
 104 containing information about the user. Avatar attribute is only present for profiles that have uploaded their
 105 avatar image to the server. Example output below:
 106
 107 <?xml version="1.0" encoding="utf-8"?>
 108 <user login="test" description="<![CDATA my car rox! ]]>" last_activity="2010-05-13 21:47:15" avatar="http://www.speedfreak-api.com/static/uploads/avatars/22.jpg"  />
 109
 110
 111 Fetching results
 112 ================
 113
 114 URL: /results/list/category_name/limit/show_unit
 115
 116 Category: For example "acceleration-0-100", "top-speed" and so on
 117 Limit: This will tell server how many results you want to get back. Results are
 118 ordered by record position starting with highest record first.
 119
 120 category_name and limit are required parameters while show_unit is optional. show_unit can have
 121 only one value which is true (string). When show_unit is specified every result will have a unit
 122 attribute where by default it's km/h. Results can have up to two decimals. Dot is used as
 123 decimal separator.
 124
 125 Below is example of what client might get back in return when sending following
 126 request: /results/list_results/acceleration-0-100/10
 127
 128 <?xml version="1.0" encoding="utf-8"?>
 129 <results category="acceleration-0-100" unit="seconds" description="Acceleration from 0 to 100 km/h">
 130     <result position="1" user="test928" date="12/1/2010" value="13" />
 131     <result position="2" user="test922" date="15/1/2010" value="12.22" />
 132     <result position="3" user="test92a" date="11/1/2010" value="11.12" />
 133     <result position="4" user="test92s" date="15/2/2010" value="10" />
 134     <result position="5" user="test92d" date="1/1/2010" value="9" />
 135     <result position="6" user="test92f" date="31/1/2010" value="8.32" />
 136     <result position="7" user="test92f" date="1/1/2010" value="7" />
 137     <result position="8" user="test92g" date="2/1/2010" value="6" />
 138     <result position="9" user="test92w" date="3/1/2010" value="5" />
 139     <result position="10" user="test92a" date="17/1/2010" value="4" />
 140 </results>
 141
 142
 143 Sending results
 144 ===============
 145
 146 URL: /results/update/category_name
 147
 148 Category: same as when fetching results
 149
 150 In order to submit results to server client needs to send XML with measurement results to
 151 category that result belongs to. Below is example of XML:
 152
 153 <?xml version="1.0" encoding="utf-8"?>
 154 <result value="14" unit="seconds" date="14/2/2010" />
 155
 156
 157 Sending route
 158 =============
 159
 160 URL:
 161
 162 Below is example of XML:
 163
 164 <?xml version="1.0" encoding="UTF-8"?>
 165 <Route Start-time="19.04.2010 21:44:49" Stop-time="19.04.2010 22:05:44" Points="4">
 166         <Point Latitude="65.0024" Longitude="25.4804" Altitude="32" Speed="29.052"/>
 167         <Point Latitude="65.0023" Longitude="25.5508" Altitude="45" Speed="29.052"/>
 168         <Point Latitude="65.0022" Longitude="25.5509" Altitude="41.5" Speed="29.052"/>
 169         <Point Latitude="65.0022" Longitude="25.551" Altitude="37.5" Speed="29.052"/>
 170 </Route>
 171
 172
 173 Logout
 174 ======
 175
 176 There is no need to logout as server is stateless, but client can mimic logout
 177 functionality by "forgetting" user credentials on the mobile device.