Difference between revisions of "API"

Revision as of 16:34, 10 February 2012

Overview

Getting Started

• First you'll need to authenticate the device you are using.
• Even though each TimeMD account has a unique "Access URL" (or "Client URL"). You'll use our dedicated API URL for all calls to the server. In this case the URL is ‘login.timemd.com’.

What You Should Know First

• TimeMD.com uses a REST interface for our API. REST is a simple format that allows you to make queries by constructing a URI containing variables and values and submitting to our API web page. The server responds with XML or JSON output containing the information that you requested.
• Each API request is composed of two parts. An action and variables for that action. Additionally, all API calls (with the exception of register_device) require an api_key parameter that proves you are logged in. Normally you won't have to worry about this though, since our PHP class handles authentication for you.
• All API output is returned in JSON format unless you add the output_format=xml option to your requests. All API requests will include a status field with a value of either ‘ok’ or ‘fail’. If the status is 'ok' there will also be a field named ‘message’ with more details. If the status is 'fail' there will also be an element named 'message' with more details.
• We recommend using HTTPS for all API requests to our Access URL
• GET vs. POST. Our API reads your actions and parameters from both GET and POST data. While examples below show parameters being posted via GET, it will work equally well if some (or all) of the parameters are passed as POST data.

API Actions

To register a device, your first login with a company's primary account login. You must pass the action ‘regiser_device’, and you must include the company's username and password:

https://login.timemd.com/login/api.php?action=register_device&username=demoent&password=demoent

In return you will get the accounts API Key. You must include the given key for all subsequent API calls related to that device (i.e. clock_out, clock_in, etc.)

<result>
 <status>ok</status>
 <message>The device has been successfully registered</message>
 <api_key>28150_1536687004</api_key>
</result>

When you receive a status of 'fail' from any API action, you'll also be given a message. For example:

<result>
   <status>fail</status>
   <message>Login credentials not recognized</message>
</result>

Tracking Time

Clocking In

Usually called Clocking-in', punching the clock or starting a timer, this call lets you start tracking time for a user.