|
TimeWellScheduled API Documentation Overview The TimeWellScheduled API allows you to call modules with the TimeWellScheduled service that respond in standard XML. Individual modules and their properties are detailed blow.
The TimeWellScheduled API isn’t your typical API in the way that it doesn’t rely on different HTTP request methods (GET/PUT/INSERT/DELETE). Instead, we’ve decided to KISS and use only GET HTTP Requests over HTTPS (at this time), and to simply pass the desired method along with the variables for the request itself in a standard, well-formatted URI. This has a number of advantages and will make your live easier when working with our API as:
We are handling all registrations internally. To get started please provide us with:
Upon receiving this information we will setup an key for you, that can be used in the development of your application. While you wait for your registration to be complete, you may want to also look into the bCrypt irreversible encryption algorithm. TimeWellScheduled utilizes bCrypt to store all passwords, and provide you with employee passwords in this encrypted format. Your application will need to verify passwords with these bCrypt hashes, meaning you will need to bCrypt-hash these on the client-end. To get comparable results, you will need the bCrypt Salt which is unique to each company; we will pass you this information when your application authenticates for the first time. For more information about bCrypt, and links to the various implementations (including Objective-C, PHP, Python, Perl, .NET, Ruby, and even JavaScript!), please visit: http://codahale.com/how-to-safely-store-a-password/ The staff at TimeWellScheduled strongly believe in the power of bCrypt, and our clients trust in our choice of using this algorithm to prevent reverse-engineering of hashes, and prevent man-in-the-middle attacks of clear-text passwords being transmitted across the network. If bCrypt implementation proves to be difficult, we’re more than happy to help! You’ll need to register for an API Key first. Please contact [email protected] for registration and setup information. Action 0: Full details regarding modules can be found in Modules section; for now, bear with us as we discuss the procedure for authentication. All request are made via HTTPS GET requests, and requires a series of variable and value pairs appended to the API URL. Here is the format of that URL, and we’ll discuss each option below: Request: Response: Upon successful validation, you will receive in the Message portion of the XML a series of values: a list of employees enclosed within <employees>
The TimeWellScheduled API allows you to call modules with the TimeWellSchedule service that respond in standard XML.
All requests to the TimeWellScheduled API must be packaged as encoded URI Strings, and appended to the API URL in a well-formed GET HTTP Request Method. Virtually all requests require an API Key and Application ID. There are additional requirements for most API calls, as follows: Remember that any data passed to the API must be in a URI string, and properly encoded (eg, %20 in place of spaces). Here is an example of how this can look in PHP: Responses The returned values are explained as follows:
The following modules are support at this time, and are to be passed in the ‘a’ attribute of each request
At this time, the following response codes are supported, and will be supplied in the ‘success’ return value in any of the module responses.
To help you better understand how our API works we’ve provided a brief example of a ‘real world’ workflow of making calls to various modules of the TimeWellScheduled API.
Step 1: The server response with XML code provided the Application ID (appid), Company ID (c) and API Key (p) match: Success is equal to 1, meaning our request was successful. We’ve been given an EventID, and in the message, we’ve been given a XML list of employees to store temporarily, some branding information, and the bCrypt Salt used to hash typed passwords and to compare against. Step 2: The server responds with XML code, indicating that this employee is on-‐time, and has a message waiting for them; it also retrieves the photo1.jpg file mentioned in the ‘a’ attribute (uploaded on a separate thread, and placed in a holding area), and attaches it to this event. The employee would then dismiss this message. Step 3: The server responds: The employee confirms the message, and the UI is reset. Step 4: The server responds: The employee confirms the message, and the UI is reset. Step 5: However, this employee tapped ‘Meal,’ but was already out on break; the server responds: The employee confirms the message, and attempts to return from break: The server responds: The employee can now punch out for their meal.
Step 6: The server responds: The employee then confirms their message. The following are some neat additional (and optional) API’s to hook into
TBD |