Update API: profile
[speedfreak] / 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: /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
50 Below is example of XML that client might send to server to register an account:
51
52 <?xml version="1.0" encoding="utf-8"?>
53 <user>
54     <login>test827</login>
55     <password>thisisaveryinsecurepassword</password>
56     <email>test@example.com</email>
57 </user>
58
59 If registration is successful server will return 200 HTTP status code along with
60 text "OK" in the response body. In other cases (invalid email, login exists etc)
61 server will return HTTP error code 400 with error message in the body text.
62
63
64 Login
65 =====
66
67 URL: /login
68
69 Because communication with server has no state there is no need to login. Client
70 might need to verify that credentials supplied by user are correct. In order to
71 do that client can send a login request which will just verify that login and password
72 are correct and user exists in database.
73
74 When making a login request you don't have to supply XML, only basic authentication.
75 If credentials are correct server will return "OK" along with HTTP status code 200.
76 In any other case it will return 401 HTTP error code along with error description.
77
78
79 Fetching results
80 ================
81
82 URL: /results/category_name/limit/show_unit
83
84 Category: For example "acceleration-0-100", "top-speed" and so on
85 Limit: This will tell server how many results you want to get back. Results are
86 ordered by record position starting with highest record first.
87
88 category_name and limit are required parameters while show_unit is optional. show_unit can have
89 only one value which is true (string). When show_unit is specified every result will have a unit
90 attribute where by default it's km/h. Results can have up to two decimals. Dot is used as
91 decimal separator.
92
93 Below is example of what client might get back in return when sending following
94 request: /results/acceleration-0-100/10
95
96 <?xml version="1.0" encoding="utf-8"?>
97 <results category="acceleration-0-100" unit="seconds" description="Acceleration from 0 to 100 km/h">
98     <result position="1" user="test928" date="12/1/2010" value="13" />
99     <result position="2" user="test922" date="15/1/2010" value="12.22" />
100     <result position="3" user="test92a" date="11/1/2010" value="11.12" />
101     <result position="4" user="test92s" date="15/2/2010" value="10" />
102     <result position="5" user="test92d" date="1/1/2010" value="9" />
103     <result position="6" user="test92f" date="31/1/2010" value="8.32" />
104     <result position="7" user="test92f" date="1/1/2010" value="7" />
105     <result position="8" user="test92g" date="2/1/2010" value="6" />
106     <result position="9" user="test92w" date="3/1/2010" value="5" />
107     <result position="10" user="test92a" date="17/1/2010" value="4" />
108 </results>
109
110
111 Sending results
112 ===============
113
114 URL: /update/category_name
115
116 Category: same as when fetching results
117
118 In order to submit results to server client needs to send XML with measurement results to
119 category that result belongs to. Below is example of XML:
120
121 <?xml version="1.0" encoding="utf-8"?>
122 <result value="14" unit="seconds" date="14/2/2010" />
123
124
125 Sending route
126 =============
127
128 URL:
129
130 Below is example of XML:
131
132 <?xml version="1.0" encoding="UTF-8"?>
133 <Route Start-time="19.04.2010 21:44:49" Stop-time="19.04.2010 22:05:44" Points="4">
134         <Point Latitude="65.0024" Longitude="25.4804" Altitude="32" Speed="29.052"/>
135         <Point Latitude="65.0023" Longitude="25.5508" Altitude="45" Speed="29.052"/>
136         <Point Latitude="65.0022" Longitude="25.5509" Altitude="41.5" Speed="29.052"/>
137         <Point Latitude="65.0022" Longitude="25.551" Altitude="37.5" Speed="29.052"/>
138 </Route>
139
140
141 Logout
142 ======
143
144 There is no need to logout as server is stateless, but client can mimic logout
145 functionality by "forgetting" user credentials on the mobile device.
146