+++ /dev/null
-API specifications for client-server communication
-==================================================
-
-
-General information
-===================
-
-This document will briefly describe API that is used in Speed Freak project.
-In this document client will be Maemo 5 application running on Nokia N900 device.
-Server will be PHP application running on api.speedfreak-app.com
-
-General technical information
-=============================
-
-XML will be used for encapsulating data sent to and received from server. XML will
-be sent using HTTP protocol as POST data. Once product is launched HTTP will be
-swapped in favor of HTTPS for additional security.
-
-All requests sent to server should satisfy following requirements:
-
-- Login and password supplied via HTTP basic authentication (not required for
-registration)
-- Post field xml should contain XML (not required in login request)
-- XML should be UTF8 encoded
-
-Server in return will respond with XML in body of the response if request was
-successful or with HTTP error code if there was problem processing the request.
-Successful requests return 200 HTTP status code.
-
-Here is the list of general errors that client might encounter:
-
-- 404: Request sent to incorrect URL
-- 500: General error during processing request
-- 403: Client has no privileges to access this resource
-- 400: Invalid request
-- 401: Failed to authenticate
-
-Registration process
-====================
-
-URL: /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:
-
-- 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.
-
-Below is example of XML that client might send to server to register an account:
-
-<?xml version="1.0" encoding="utf-8"?>
-<user>
- <login>test827</login>
- <password>thisisaveryinsecurepassword</password>
- <email>test@example.com</email>
-</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.
-
-
-Login
-=====
-
-URL: /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
-do that client can send a login request which will just verify that login and password
-are correct and user exists in database.
-
-When making a login request you don't have to supply XML, only basic authentication.
-If credentials are correct server will return "OK" along with HTTP status code 200.
-In any other case it will return 401 HTTP error code along with error description.
-
-
-Fetching results
-================
-
-URL: /results/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.
-
-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
-
-<?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.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.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" />
- <result position="10" user="test92a" date="17/1/2010" value="4" />
-</results>
-
-
-Sending results
-===============
-
-URL: /update/category_name
-
-Category: same as when fetching results
-
-In order to submit results to server client needs to send XML with measurement results to
-category that result belongs to. Below is example of XML:
-
-<?xml version="1.0" encoding="utf-8"?>
-<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.
-
projects / speedfreak / blobdiff