Skip to content

Latest commit

 

History

History
73 lines (49 loc) · 2.96 KB

README.md

File metadata and controls

73 lines (49 loc) · 2.96 KB
Raw

How to Make Friends and Use the Bidsketch API

Get an API token

To get started with the API you'll want to get an api token.

You can see how to get an API token here: http://help.bidsketch.com/article/76-using-the-bidsketch-api

Making a request

Your adventure with the Bidsketch API starts at https://bidsketch.com/api/v1. This is the beginning of every end point.

curl https://bidsketch.com/api/v1/proposals -H 'Authorization: Token token="yourtoken"'

Authentication

We use HTTP token authentication to identify and authorize accounts for the API. All you need to do as a developer is ask Bidsketch users to get their api token and pass it along in an authorization header.

Authorization: Token token="abc123abc123abc123abc123abc123"

Users can find their api tokens at [subdomain].bidsketch.com/account/api_tokens. Keep in mind that only Admin users can manage api tokens.

Versioning

We're starting this api with a nice, comfortable version 1, hence the v1/ part of the api path. This just means that you can trust that v1 will keep working the way you expect it. When we have to introduce something that could break what you have worked so hard to build, we'll bump the version of the API up one.

Rate Limits

We limit requests for each token to 100 requests in 20 seconds.

Status Codes

Code Reason When You'll See It
200 OK. Cool. Successful GET, PUT, and POST requests
204 No Content Successful DELETE requests
400 Bad Request No API token was provided
401 Unauthorized Revoked or Invalid API token
404 Not Found Can't find the API resource or URL you asked for
422 Unprocessable Entity Invalid data when creating or updating
426 Upgrade Required The account has hit a client or proposal limit
500 Internal Server Error Something went very, very wrong

Errors

Whenever you get a 422 Unprocessable Entity code, it'll have a json-formatted array of errors for what went wrong:

{
  "errors": [
    "email cannot be blank",
    "first_name is far too silly",
    "last_name matches first_name. Who has two first names?"
  ]
}

Pagination

By default, we paginate collections and limit them to 100 objects per request. You can request specific pages by appending a page parameter to the URL. You can

  • GET /clients.json?page=3 would get the 201st to 300th clients
  • GET /proposals.json?per_page=2 would get the first two proposals
  • GET /sections.json?page=8&per_page=1 would get a collection of only the eighth section

Libraries and Contributing

This API is pretty new, so we don't have any libraries available just yet. As they become available, we'll link them them here. If you've written a library for the Bidsketch API and would like to contribute, let us know at support@bidsketch.com!