Bike Index API V3

The Bike Index is open source. You can view the source code on GitHub—the API is in app/controllers/api/v3 and the tests for it are in spec/requests/api/v3.

If you encounter any errors here (or anywhere on Bike Index), please submit an issue on GitHub.

If you have questions contact admin@bikeindex.org.

This documentation displays the port number in the demo requests - e.g. bikeindex.org:443/api/v3/search. While this works, it’s unnecessary. You can remove the :443 - e.g. bikeindex.org/api/v3/search.

This documentation isn’t tested or supported in IE, we recommend you use a different browser

Introduction

The Bike Index API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, including errors.

CORS

Every endpoint on the Bike Index API supports Cross-Origin Resource Sharing (CORS).

The CORS spec allows web applications to make cross domain AJAX calls without using workarounds such as JSONP. For more information about CORS, read this article, or the spec.

Errors

The Bike Index uses HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with our servers.

Errors respond with a JSON object with a description of the error under the key error e.g. {"error":"Couldn't find Bike with id=XXXXXX"}.

The word “bike”

We use the work “bike” throughout this documentation to mean anything that is registered (be it a tandem, ice-cream cart or standard bicycle). If we are referring specifically to standard bicycles, we make note of that.

You can view all the types of cycles (or vehicles) we accept.

Bike URLs

The HTML pages of Bike Index follow the same pattern as the API - the url for a bike is https://bikeindex.org/bikes/{bike_id}.

Time

Bike Index API V3 displays everything in UTC unix timestamps (integers). All time parameters you send need to use timestamps as well.

Authentication

The Bike Index uses OAuth2. Create an application and use an access token for any requests that need authorization.

Endpoints with Red Stars (*) require an access token to use.

There is increased rate limiting for unauthenticated requests - including an access token in all requests (even when not required) is a good idea.

Bike Index API V3 endpoints

Your applications: Add an application

You don't have any applications set up! To be able to use the API you will need to create an application and generate an access token.

Add an application here.

OAuth2 - Authentication on Bike Index

The Bike Index uses OAuth2.

Plugins and external libraries

Ruby: omniauth-bike-index gem
Javascript: HelloJS Bike Index Module

OAuth Flows

There are two supported ways of authenticating with Bike Index through OAuth2:

Authorization flow, also called Explicit grant flow. If you create a token on this page, this what the token is created with.
Client-side flow, also called Implicit grant flow or Bearer flow.

The Authorization flow enables long lived access through refresh tokens (instead of logging out the user every hour), is more secure, and is generally what you should be using. Learn more about Authorization flow in OAuth2.

The Client-side flow is good for client-side javascript apps. Here’s an article on Client-side flow in OAuth2.

There will be rate limiting on the future for non-authenticated requests - so if you have an access token, consider using it for everything.

Applications you’ve authorized

Review the applications you’ve authorized at /oauth/authorized_applications.

Sending your access tokens in requests

By default we authenticate you with authentication in the header. If authentication is not found in the authorization header, then it falls back to the parameters. We recommend putting the authentication information in the header ("Authorization" => "Bearer #{token}").

All the authenticated requests in this documentation put the access token in the parameters for clarity, though.

Refresh tokens

Since tokens provide access to someone’s account, one of the ways OAuth2 keeps things secure is by having tokens expire - so if someone compromises an access token, they don’t have unlimited access to an account. The Bike Index expires tokens after 1 hour.

When your access token expires, you can get a new one by making a POST request with your app id and the refresh token:

POST https://bikeindex.org/oauth/token?grant_type=refresh_token&client_id={app_id}&refresh_token={refresh_token}