X-Git-Url: http://git.maemo.org/git/?p=speedfreak;a=blobdiff_plain;f=documents%2FAPI.txt;h=36c13a498120fbe615a2822237aef2c560f9b449;hp=e29585dcc16986d050a8f30bb03814a2a9759470;hb=8785db5df89a4d417ffb965f919b53be8138fdd5;hpb=8e2751b9dddac3dfb08e3016bc4efcd73404ffe8

diff --git a/documents/API.txt b/documents/API.txt
index e29585d..36c13a4 100644
--- a/documents/API.txt
+++ b/documents/API.txt
@@ -38,7 +38,7 @@ Here is the list of general errors that client might encounter:
 Registration process
 ====================
 
-URL: /register
+URL: /users/register
 
 Every single client should register before it can send own measurement results or
 fetch other's results. During registration client has to supply following information:
@@ -46,6 +46,7 @@ fetch other's results. During registration client has to supply following inform
 - Login: This is 3-12 charecters long nickname that has to be unique
 - Password: 6-255 charectors long password
 - Email: email address that will be used for password recovery etc. Has to be unique.
+- Description: Additional information that user might want to supply.
 
 Below is example of XML that client might send to server to register an account:
 
@@ -54,17 +55,20 @@ Below is example of XML that client might send to server to register an account:
     <login>test827</login>
     <password>thisisaveryinsecurepassword</password>
     <email>test@example.com</email>
+    <description>My car is cool</description>
 </user>
 
 If registration is successful server will return 200 HTTP status code along with
 text "OK" in the response body. In other cases (invalid email, login exists etc)
 server will return HTTP error code 400 with error message in the body text.
 
+User can also supply avatar image as POST field named "avatar". Please notice that
+avatar image must not exceed 100 kilobytes in size and should be supplied in Jpeg format.
 
 Login
 =====
 
-URL: /login
+URL: /users/login
 
 Because communication with server has no state there is no need to login. Client
 might need to verify that credentials supplied by user are correct. In order to
@@ -76,28 +80,59 @@ If credentials are correct server will return "OK" along with HTTP status code 2
 In any other case it will return 401 HTTP error code along with error description.
 
 
+List all users
+==============
+
+URL: /users/list_all
+
+Using this you can get XML containing all registered users. Last activity attribute shows date and time
+when user has contacted the server. Example output below:
+
+<?xml version="1.0" encoding="utf-8"?>
+<users>
+	<user login="test" description="<![CDATA my car rox! ]]>" last_activity="2010-05-13 21:47:15"  />
+	<user login="test1" description="<![CDATA my car rox too! ]]>" last_activity="2010-05-13 21:28:00"  />
+</users>
+
+
+Viewing user's profile
+======================
+
+URL: /users/info/username
+
+Username is in this case username of user who's information you want to retrieve. In return you will get XML
+containing information about the user. Avatar attribute is only present for profiles that have uploaded their
+avatar image to the server. Example output below:
+
+<?xml version="1.0" encoding="utf-8"?>
+<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"  />
+
+
 Fetching results
 ================
 
-URL: /results/category_name/limit
+URL: /results/list/category_name/limit/show_unit
 
 Category: For example "acceleration-0-100", "top-speed" and so on
 Limit: This will tell server how many results you want to get back. Results are
 ordered by record position starting with highest record first.
 
-Both parameters are required.
+category_name and limit are required parameters while show_unit is optional. show_unit can have
+only one value which is true (string). When show_unit is specified every result will have a unit
+attribute where by default it's km/h. Results can have up to two decimals. Dot is used as
+decimal separator.
 
 Below is example of what client might get back in return when sending following
-request: /results/acceleration-0-100/10
+request: /results/list_results/acceleration-0-100/10
 
 <?xml version="1.0" encoding="utf-8"?>
 <results category="acceleration-0-100" unit="seconds" description="Acceleration from 0 to 100 km/h">
     <result position="1" user="test928" date="12/1/2010" value="13" />
-    <result position="2" user="test922" date="15/1/2010" value="12" />
-    <result position="3" user="test92a" date="11/1/2010" value="11" />
+    <result position="2" user="test922" date="15/1/2010" value="12.22" />
+    <result position="3" user="test92a" date="11/1/2010" value="11.12" />
     <result position="4" user="test92s" date="15/2/2010" value="10" />
     <result position="5" user="test92d" date="1/1/2010" value="9" />
-    <result position="6" user="test92f" date="31/1/2010" value="8" />
+    <result position="6" user="test92f" date="31/1/2010" value="8.32" />
     <result position="7" user="test92f" date="1/1/2010" value="7" />
     <result position="8" user="test92g" date="2/1/2010" value="6" />
     <result position="9" user="test92w" date="3/1/2010" value="5" />
@@ -108,7 +143,7 @@ request: /results/acceleration-0-100/10
 Sending results
 ===============
 
-URL: /update/category_name
+URL: /results/update/category_name
 
 Category: same as when fetching results
 
@@ -119,9 +154,24 @@ category that result belongs to. Below is example of XML:
 <result value="14" unit="seconds" date="14/2/2010" />
 
 
+Sending route
+=============
+
+URL:
+
+Below is example of XML:
+
+<?xml version="1.0" encoding="UTF-8"?>
+<Route Start-time="19.04.2010 21:44:49" Stop-time="19.04.2010 22:05:44" Points="4">
+	<Point Latitude="65.0024" Longitude="25.4804" Altitude="32" Speed="29.052"/>
+	<Point Latitude="65.0023" Longitude="25.5508" Altitude="45" Speed="29.052"/>
+	<Point Latitude="65.0022" Longitude="25.5509" Altitude="41.5" Speed="29.052"/>
+	<Point Latitude="65.0022" Longitude="25.551" Altitude="37.5" Speed="29.052"/>
+</Route>
+
+
 Logout
 ======
 
 There is no need to logout as server is stateless, but client can mimic logout
-functionality by "forgetting" user credentials on the mobile device.
-
+functionality by "forgetting" user credentials on the mobile device.
\ No newline at end of file