feedback

The 1DayLater API

NOTE - The API will remain in Beta for a few months after the launch of the 1DayLater service, this is to allow time for the API to mature - we want the form and function to take to be just right! However - we have a system to highlight the features that are: stable, under review and unstable, see Introducing the API for more details

The API allows developers and coders to access many of the 1DayLater features and data through an easy to use interface. This document is a reference to the API and serves as guide to those wanting to build on 1DayLater.

To quickly grok the 1DayLater API, we've created a simple use-case diagram and explanation. It's only 60 seconds long, and we recommend you play it through at least once before getting your hands dirty...

Using the 1DayLater API couldn't be easier, you simply submit data to the API and get a response. There's only 2 type of response: success and failure. A successful response returns exactly what you expect: all the data you need, plus any messages from the system. The messages are there to notify you about minor problems or automated actions. For example: if you don't pass a colour when the API expects one, a random colour is picked for you and a message is returned. A failed response occurs when you do daft things, and the only data returned is a list of errors. The submit is made up of 3 sets of variables posted to the API: Firstly are the OAuth variables, which verify the user and request, secondly are the action variables, which describe what you want to do and how you want your response to look, and lastly are the variables that are specific to the action. You can find in-depth information about any part of the API using the tool found on the API page.
click to view the 60-second animation


Table of Contents


Introducing the API

As a result of our agile development process the 1DayLater API sees minor changes often, and major changes occasionally. But don't let this scare you away from using the service - we have a very simple traffic-light system to denote which features are:

  • Stable
  • Under Review
  • Unstable

You can then make programming decisions based on the availability of the features - if you have any ideas please do send us an email


Authentication with OAuth

1DayLater uses OAuth to authenticate applications and their requests. OAuth is an open protocol specifically created for API's, its purpose is to allow 3rd party applications to talk to 1DayLater without having to ask for a users credentials.

We adhere to the OAuth specification with the following settings

Specification
Supported OAuth Spec 1.0a
Signature Method HMAC-SHA1
Request Token Expiration 5 minutes, single use only
Access Token Expiration never, user revocation only

Before you can access the API and authorize requests you must first register your application with 1DayLater, your application is assigned a unique consumer key that we use to identify your requests. Applications that you register will be assinged to your user account, and can be viewed and editied from your homepage.

Registering you application
App signup http://1daylater.com/app_signup

Finally, the authentication flow uses the following endpoints

Endpoints
Get request token http://1daylater.com/get_request_token
Authorize token http://1daylater.com/authorize
Get access token http://1daylater.com/get_access_token

Once your application is registered, and you are successfully authorizing tokens, you must pass the token to all API requests - at no point should you ask users for their 1DayLater login details


Handling responses

This should make you smile - we've organised the 1DayLater responses to be ultra easy to understand and handle by making them all act in the same manner. That is, regardless of what you request, the responses will always be structured in the same way!

Lets say you make a generic request, the response data is semantic, the names and ids represent the returned data, ie:

  {
    user: { user },
    projects: { projects },
    entries: { entries }
  }

As you can clearly see, your application should update it's user information, and the projects and entries that are contained within their respective objects!

The reason that multiple objects are returned is so that you can be sure to have all the relevent data at hand. For example, if you add or update an entry, it's project will be updated (it contains a total number of minutes) as should the user (for the same reason).


The 1DayLater API tool!

loading...

Data reference

This reference is shown as JSON - the structure remains the same for XML.

Every request made returns an object, containing any number of the following objects...


{ user }

  user: {
    first_name: "David",
    last_name:  "King",
    email:      "david@1daylater.com",
    joined:     "2009-05-14",
    currency:   "£"
  }

{ projects }

The time, expense, receipt, distance, first and last variables relate to the context of your request - for example, if you do a search for entries within a date-range, then the project will contain the totals for that date-range.

  projects: {
    1: {
      id:       1,
      name:     "1DayLater",
      nickname: "odl",
      colour:   "D47700"
      time:     "1260.00",
      expense:  "500.00",
      receipt:  "1000.00",
      distance: "250.00",
      first:    "2009-05-14",
      last:     "2009-10-26"
    },
    ...
  }

{ entries }

  entries: {
    1839: {
      id:         1839,
      value:      "2h",
      time:       "120.00",
      expense:    "0.00",
      receipt:    "0.00",
      distance:   "0.00",
      note:       "Writing the privacy policy",
      project_id: 1,
      date:       "2009-10-24"
      start_time: "09:00:00",
      end_time:   "11:00:00"
    },
    ...
  }

{ activity }

  activity: {
    1: {
      id:       1,
      name:     "1DayLater",
      nickname: "odl",
      colour:   "D47700",
      interval: "daily",
      minutes: {
        0: 100,
        -1: 100,
        -2: 60,
        -3: 90,
        ...
      }
    }
    ...
  }

{ messages }

Messages are returned alongside the normal response to show that something "extra" has happenned.

For example, if you try to update a project and send a malformed colour, the colour wont be updated and a message will be returned with the normal response in toe.

  messages: [
    "General message",
    ...
  ]

{ errors }

Errors are returned with malformed or bad requests.

  errors: [
    "Error message",
    ...
  ]

A note about currency symbols

Our system deals with Unicode UTF-8 characters for currency symbols. We accept the following as valid currency symbols:

Note: We compiled this list using these references:


Have you built something cool?

We'd love to know what you've created! Would you like us to link to your project? Integrate your killer ideas? Give you free stuff? Send us an email and we'll figure something out, there's no rules here except that a good chinwag is an excellent starting point!

And (in advance), thanks for having a play, kudos.