88 Miles

API Documentation

• Introduction

  • Home
  • The Basics
  • Authentication

• Staff

  • index
  • show
  • create
  • update
  • destroy

• Companies

  • index
  • show
  • create
  • update
  • destroy

• Projects

  • index
  • show
  • create
  • update
  • destroy
  • punch_in
  • punch_out

• Shifts

  • index
  • show
  • create
  • update
  • destroy

• Timezones

  • index

• Time

  • current

• User

  • index

Authentication

There are two ways to authenticate against the 88 Miles API: Basic Authentication and OAuth. While OAuth is slightly more difficult to setup, it is the preferred method for third party, public application as it gives users more control over what applications have access to their data.

OAuth

OAuth is a token based authentication system, which means your users can access their 88 Miles data without having to give you their username or password. Many popular languages already support OAuth, which should ease integration with you application. You can see if your favourite language is supported on the OAuth website.

Using an existing library will speed up your development, so it is recommended you have a look at one first. If you are interested in how the protocol works, or need more information to debug the require process, read on…

Getting Started

When a user wants to authorise your application against 88 Miles, your application will:

• Retrieve a request token.
• Request user authorisation. The user does this after they login to 88 Miles.
• Exchange the request token for an access token

If you application is not web-based (and it is using OAuth 1.0a), the user will have to cut-and-paste a authorization number to complete the last step.

Once your application has an application token, it can then read and write to that user’s 88 Miles account.

If you are interested in the OAuth protocol, check out the guide at http://hueniverse.com/oauth/.

Registering an application

The first step to connecting your application to OAuth is to register your application.

While creating an application, you will be asked whether your application is a desktop or web application. One of the parameters you will be asked to supply is a callback_url which is an optional parameter, which tells 88 Miles where to redirect the user once authorisation is complete. If your application is a desktop application, leave the field blank; or if you wish to use out-of-band flow, you would supply an oauth_callback_url of "oob".

If you choose to make you application public, it will show up on 88 Miles third party apps list.

After registration, you will receive a consumer key and consumer secret. You will need to insert this in to your application so you can sign all the requests.

Signing a request

All OAuth 1.0a requests need to be signed, so 88 Miles can make sure your application is really allowed to access the users data.

The signature string is one area that can cause issues when debugging your application, as any erronous or incorrect characters in the string you are signing will change the signature.

The signature string has the following components:

• the HTTP method being used
• an ampersand
• the complete, URL-encoded base URL being accessed, including the path (but not query parameters)
• an ampersand
• All the query and POST parameters (including any OAuth parameters), sorted lexigraphically.

Each query and POST parameter should be URL encoded seperately; all equal signs should be encoded to %3D; and all ampersands encoded to %26

The OAuth standard acceptes signatures generated by different methods. 88 Miles requires that all OAuth requests be signed using the HMAC-SHA1 algorithm.

Retrieve a request token

Before you can make requests to the 88 Miles API, you need to get authorisation from the user. The first step it to get a request token.

The 88 Miles request token end point is http://www.88miles.net/oauth/request_token

A request-token request requires six variables to be POSTed. In this example, we will use:

• oauth_callback: http://locahost:3000/oauth/callback
• oauth_consumer_key: 3K7hjTW97NRdgYFBABMY
• oauth_nonce: as8fjsd3
• oauth_signature_method: HMAC-SHA1
• oauth_timestamp: 1275433353
• oauth_version: 1.0
• consumer secret WkotqxeagBOYEIRnrvhUC1xIOVYpdFMM5u7gXEVG

First, we sort all the parameters used in our request and formulate a signature base string. This builds the following signature base string:

POST&http%3A%2F%2Fwww.88miles.new%2Foauth%2Frequest_token&oauth_callback%3Dhttp%253A%252F%252Flocalhost%253A3000%252Fooauth%252Fcallback%253D11%26oauth_consumer_key%3D3K7hjTW97NRdgYFBABMY%26oauth_nonce%3Das8fjsd3%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1275433353%26oauth_version%3D1.0

Since this request doesn't have an oauth_token or oauth_token_secret, we don't inlcude an oauth_token field in our base string and we don't use an oauth_token_secret when calculating the signing key. Our signing key is (notice the dangling ampersand at the end):

MCD8BKwGdgPHvAuvgvz4EQpqDAtx89grbuNMRd7Eh98&

We now use the signing key to create an oauth_signature by signing the base string using the signing key. The resultant oauth_signature is:

8wUi7m5HFQy76nowoCThusfgB+Q=

Now that we have our signature, we have everything we need to make the request to the endpoint http://www.88miles.net/oauth/request_token. Now we just generate an HTTP header called "Authorization" with the relevant OAuth parameters for the request:

OAuth oauth_nonce="as8fjsd3", oauth_callback="http%253A%252F%252Flocalhost%253A3000%252Fooauth%252Fcallback", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1275433353", oauth_consumer_key="3K7hjTW97NRdgYFBABMY", oauth_signature="8wUi7m5HFQy76nowoCThusfgB%2BQ%3D", oauth_version="1.0"

When 88 Miles receives the request, it will respond with an oauth_token and oauth_token_secret (collectively, your "request token"). The response to this particular request would have looked like:

oauth_token=8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc&oauth_token_secret=x6qpRnlEmW9JbQn4PQVVeVG8ZLPEx6A0TOebgwcuA

You will need to story these tokens temporarily, as you will need to exchange them for an authorisation token after the user has granted your application access to their data.

Sending the user to authorization

The endpoint for the authorization url is http://www.88miles.net/oauth/authorize. It must have a single query parameter attached called oauth_token with the value set to the oauth_token you received in the request token step. In the example above, the oauth_token was "8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc". Using this token to generate an authorization URL results in:

http://www.88miles.net/oauth/authorize?oauth_token=8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc

If the user will have to login (if they aren't already) then they will be asked to authorise your application. If they select "Yes", you application will be given access to the users data. If you supplied a callback URL, the user will be automtacally redirected to that URL, otherwise they will be given a confirmation key which they will need to enter into your application manually.

If you are using the callback flow, your oauth_callback should have received back your oauth_token (the same that you sent, your "request token") and a field called the oauth_verifier

oauth_token=8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc&oauth_verifier=pDNg57prOHapMbhv25RNf75lVRd6JDsni1AJJIDYoTY

Exchanging a request token for an access token

The final step in the authorisation step is to exchange the request token, that was provided earlier, for an authorisation token.

Ahe access token end point is http://www.88miles.net/oauth/access_token

You will need to send the following parameters:

• oauth_consumer_key 3K7hjTW97NRdgYFBABMY
• oauth_nonce aDdkmf2
• oauth_signature_method HMAC-SHA1
• oauth_token 8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc
• oauth_timestamp 1275498117
• oauth_verifier pDNg57prOHapMbhv25RNf75lVRd6JDsni1AJJIDYoTY
• oauth_version 1.0

And though it is only used in the signing part of the request, the oauth_token_secret is still x6qpRnlEmW9JbQn4PQVVeVG8ZLPEx6A0TOebgwcuA.

POST&https%3A%2F%2Fwww.88miles.net%2Foauth%2Faccess_token&oauth_consumer_key%3D3K7hjTW97NRdgYFBABMY%26oauth_nonce%3DaDdkmf2%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1275498117%26oauth_token%3D8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc%26oauth_verifier%3DpDNg57prOHapMbhv25RNf75lVRd6JDsni1AJJIDYoTY%26oauth_version%3D1.0

We create a composite signing key using both our oauth_consumer_secret and our oauth_token_secret (request token secret) by joining them with an ampersand:

MCD8BKwGdgPHvAuvgvz4EQpqDAtx89grbuNMRd7Eh98&x6qpRnlEmW9JbQn4PQVVeVG8ZLPEx6A0TOebgwcuA

Then we sign our request, with the resultant OAuth signature:

PUw/dHA4fnlJYM6RhXk5IU/0fCc=

Now that we have our oauth_signature, we're ready to POST the request to 88 Miles, so we create our HTTP Authorization header again using the relevant OAuth parameters, including the oauth_token (request token) we are exchanging for the access tokens.

OAuth oauth_nonce="aDdkmf2", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1275498117", oauth_consumer_key="3K7hjTW97NRdgYFBABMY", oauth_token=" 8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc", oauth_verifier="pDNg57prOHapMbhv25RNf75lVRd6JDsni1AJJIDYoTY", oauth_signature="PUw%2FdHA4fnlJYM6RhXk5IU%2F0fCc%3D", oauth_version="1.0"

When this request completes, 88 Miles will respond with an oauth_token and oauth_token_secret (collectively, your "access token"). This access token becomes you key to the users data, and are required in every subsequent request.

oauth_token=Jxq8aYUDRmykzVKrgoLhXSq67TEa5ruc4GJC2rWimw&oauth_token_secret=J6zix3FfA9LofH0awS24M3HcBYXO5nI1iYe8EfBA

Making an API request

Now that your application has an oath_token and an oauth_token_secret, you can access the user's data. If your application was requesting a list of all the suer's companies, you would construct the following request:

• GET
• oauth_consumer_key 3K7hjTW97NRdgYFBABMY
• oauth_nonce d9HHydl2
• oauth_signature_method HMAC-SHA1
• oauth_token Jxq8aYUDRmykzVKrgoLhXSq67TEa5ruc4GJC2rWimw
• oauth_timestamp 1292372938
• oauth_version 1.0

Now create a signature base string:

GET&http%3A%2F%2Fwww.88mies.net%2F1%2Fcompanies.json&oauth_consumer_key%26GDdmIQH6jhtmLUypg82g%26oauth_nonce%3Dd9HHydl2%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1292372938%26oauth_token%3DJxq8aYUDRmykzVKrgoLhXSq67TEa5ruc4GJC2rWimw%26oauth_version%3D1.0

Now, create a composite signing key using both the oauth_consumer_secret and the oauth_token_secret tied to my access token:

MCD8BKwGdgPHvAuvgvz4EQpqDAtx89grbuNMRd7Eh98&J6zix3FfA9LofH0awS24M3HcBYXO5nI1iYe8EfBA

Get a signature by signing the base-string:

yOahq5m0YjDDjfjxHaXEsW9D+X0=

Create a HTTP Authorisation header

OAuth oauth_nonce="d9HHydl2", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1292372938", oauth_consumer_key="3K7hjTW97NRdgYFBABMY", oauth_token="Jxq8aYUDRmykzVKrgoLhXSq67TEa5ruc4GJC2rWimw", oauth_signature="yOahq5m0YjDDjfjxHaXEsW9D%2BX0%3D", oauth_version="1.0"

This request should return a list of the users companies in JSON format.

Glossary

• oauth_nonce a unique identifier for your request, generated by you. Twitter will only allow a nonce to be used once by your application. Prevents replayed requests.
• oauth_timestamp an integer representing the number of seconds that have passed since the unix epoch.
• oauth_verifier a string sent to you on your OAuth callback or provided to a user on the authentication flow, depending on whether you are using out-of-band mode or not. It is required to be sent back on the access token step.
• out of band mode Instead of providing a URL-based callback when acquiring a request token, "oob" is supplied. Once the user has given Twitter their account credentials, they are presented with a screen containing a PIN code and are asked to enter this code into the application. The application then sends this PIN as an oauth_verifier to the access token step to complete the exchange.
• signature base string an assembled string that is signed using a signing key to create a signature. In OAuth 1.0A
• signing key the string used as the "secret key" to sign a request.

Basic Authentication

Basic authentication is the simplest way to access the 88 Miles API. It requires the user’s username and password, so it isn’t recommended for use applications that you are exposing to the public (See OAuth if you are building a website that needs to access the API). If you really want to use basic authentication, it is recommended to use SSL when accessing the API.

Most HTTP libraries support basic authentication out of the box. In the following example, we will use cURL which is installed on many UNIX based computers (including OSX). It is also available for Windows.

Example

The following example will return a list of the user’s companies, in XML format.

curl -u 'username:password' http://www.88miles.net/companies.xml

It also works with JSON as well:

curl -u 'username:password' http://www.88miles.net/companies.json