The 1DayLater API

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...

click to view the 60-second animation

Table of Contents

• Introducing the API - using the API and documentation
• Authentication with OAuth - details of our implimentation
• Handling responses - read this once or twice I reckon
• The 1DayLater API tool! - you'll use this the most!
• Data reference - example data for your perusal
• { user }
• { projects }
• { entries }
• { activity }
• { messages }
• { errors }
• A note about currency symbols - only for *really* interested people
• Have you built something cool? - we want to hear from you!

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

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.

Finally, the authentication flow uses the following endpoints

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).

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: {
    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:

• A list of currencies
• Most currency unicode characters
• and some creative googling!

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.