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: /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: - 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: test827 thisisaveryinsecurepassword test@example.com My car is cool 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: /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 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. 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: 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: Fetching results ================ 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. 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/list_results/acceleration-0-100/10 Sending results =============== URL: /results/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: Fetching list of categories =========================== URL: /results/categories Sends back XML containing all categories found on the server Example XML below: acceleration-0-10 acceleration-0-40 acceleration-0-100 Sending route ============= URL: Below is example of XML: 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.