Permalink
Browse files

Update README.md

Suggest changes to improve clarity and consistency
  • Loading branch information...
hillaryfraley committed Jul 28, 2016
1 parent dd029be commit 66596fa97d47954fe3aaa3c342b98f3dbb2b2f62
Showing with 43 additions and 36 deletions.
  1. +43 −36 README.md
@@ -1,38 +1,38 @@
The Basecamp 3 API
==================
Welcome to the Basecamp 3 API! Looking to integrate your service with Basecamp 3, or create your own app in concert with data inside of Basecamp 3? We're happy to have you!
Welcome to the Basecamp 3 API! If you're looking to integrate your application with Basecamp 3 or create your own application in concert with data inside of Basecamp 3, you're in the right place. We're happy to have you!
Compatibility with previous Basecamp APIs
-----------------------------------------
The Basecamp 3 API is not compatible with the [Basecamp Classic API](https://github.com/basecamp/basecamp-classic-api) or the [Basecamp 2 API](https://github.com/basecamp/bcx-api). All integrations will start fresh with the new API. The core ingredients are the same, though: this is a REST-style API that uses JSON for serialization and OAuth 2 for authentication.
The Basecamp 3 API is not compatible with the [Basecamp Classic API](https://github.com/basecamp/basecamp-classic-api) or the [Basecamp 2 API](https://github.com/basecamp/bcx-api). All integrations will start fresh with the new API. The core ingredients are the same, though: Basecamp 3 is a REST-style API that uses JSON for serialization and OAuth 2.0 for authentication.
What's different?
-----------------
If you've used a previous version of the Basecamp API, you will need to adapt your integration code. Notable changes:
If you've used a previous version of the Basecamp API, you need to adapt your integration code. Here are some notable changes for the Basecamp 3 API:
- We're requiring OAuth for [authentication](#authentication). No more Basic auth.
- We require OAuth 2.0 for [authentication](#authentication)—no more Basic authentication
- All requests must end in `.json`
- [Pagination](#pagination) is now performed via the `Link` and `X-Total-Count` headers.
- Projects are now called Basecamps.
- [Pagination](#pagination) is performed via the `Link` and `X-Total-Count` headers
- Projects are called Basecamps
Making a request
----------------
All URLs start with **`https://3.basecampapi.com/999999999/`**. HTTPS only. The path is prefixed with the account ID, but no `/api/v1` API prefix. Also note the different domain!
All URLs start with **`https://3.basecampapi.com/999999999/`**. URLs are HTTPS only. The path is prefixed with the account ID, but no `/api/v1` API prefix. Also, note the different domain!
To make a request for all the projects on your account, you'd append the projects index path to the base url to form something like https://3.basecampapi.com/999999999/projects.json. In cURL, that looks like:
To make a request for all the projects on your account, append the `projects` index path to the base URL to form something like `https://3.basecampapi.com/999999999/projects.json`. In cURL, it looks like this:
``` shell
curl -H "Authorization: Bearer $ACCESS_TOKEN" -H 'User-Agent: MyApp (yourname@example.com)' https://3.basecampapi.com/999999999/projects.json
```
To create something, it's the same deal except you also have to include the `Content-Type` header and the JSON data:
To create something, it's the same idea, but you also have to include the `Content-Type` header and the JSON data:
``` shell
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
@@ -42,14 +42,14 @@ curl -H "Authorization: Bearer $ACCESS_TOKEN" \
https://3.basecampapi.com/999999999/projects.json
```
That's all! Throughout this guide we've included "Copy as cURL" examples. If you'd like to try this out in your shell, copy your OAuth Access token into your clipboard and run:
Throughout the Basecamp 3 API docs, we include "Copy as cURL" examples. To try the examples in your shell, copy your OAuth 2.0 access token into your clipboard and run:
``` shell
export ACCESS_TOKEN=PASTE_ACCESS_TOKEN_HERE
export ACCOUNT_ID=999999999
```
Then you should be able to easily copy + paste any example from our docs. After pasting a cURL example, you could pipe it to a JSON pretty printer to make it a little more readable. Try [jsonpp](https://jmhodges.github.io/jsonpp/) or `json_pp` on OSX:
Then you should be able to copy/paste any example from the docs. After pasting a cURL example, you can pipe it to a JSON pretty printer to make it more readable. Try [jsonpp](https://jmhodges.github.io/jsonpp/) or `json_pp` on OSX:
``` shell
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/999999999/projects.json | json_pp
@@ -58,68 +58,75 @@ curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/99999
Authentication
--------------
If you're making a public integration with Basecamp for others to enjoy, you must use OAuth 2. This allows users to authorize your application to use Basecamp on their behalf without having to copy/paste API tokens or touch sensitive login info.
If you're making a public integration with Basecamp for others to enjoy, you must use OAuth 2.0. OAuth 2.0 allows users to authorize your application to use Basecamp on their behalf without having to copy/paste API tokens or touch sensitive login information.
Read the [authentication guide](https://github.com/basecamp/api/blob/master/sections/authentication.md) to get started.
Identify your app
-----------------
Identifying your application
----------------------------
You must include a `User-Agent` header with **both**:
* The name of your application
* A link to your application or your email address
You must include a `User-Agent` header with the name of your application and a link to it or your email address so we can get in touch in case you're doing something wrong (so we may warn you before you're blacklisted) or something awesome (so we may congratulate you). Here's a couple of examples:
We use this information to get in touch if you're doing something wrong (so we can warn you before you're blacklisted) or something awesome (so we can congratulate you). Here are examples of acceptable `User-Agent` headers:
User-Agent: Freshbooks (http://freshbooks.com/contact.php)
User-Agent: Fabian's Ingenious Integration (fabian@example.com)
* `User-Agent: Freshbooks (http://freshbooks.com/contact.php)`
* `User-Agent: Fabian's Ingenious Integration (fabian@example.com)`
If you don't supply this header, you will get a `400 Bad Request` response.
If you don't include a `User-Agent` header, you'll get a `400 Bad Request` response.
JSON only
---------
We use JSON for all API data. Style: no root element and snake\_case for object keys. This means that you have to send `Content-Type: application/json; charset=utf-8` when you're POSTing or PUTing data into Basecamp. All API URLs end in .json to indicate that they return JSON.
We use JSON for all API data. The style is no root element and snake\_case for object keys. This means that you have to send the `Content-Type` header `Content-Type: application/json; charset=utf-8` when you're POSTing or PUTing data into Basecamp. All API URLs end in `.json` to indicate that they return JSON.
You'll receive a `415 Unsupported Media Type` response code if you attempt to use a different URL suffix or leave out the `Content-Type` header.
You'll receive a `415 Unsupported Media Type` response code if you don't include the `Content-Type` header or you try to use a different URL suffix than `.json`.
Pagination
----------
Most collection APIs paginate their results. The first request returns up to 50 records. The Basecamp 3 API follows the [RFC5988 convention](https://tools.ietf.org/html/rfc5988) of using the `Link` header to provide URLs for the `next` page. Follow this URLs to retrieve the next page of data, and please don't build the pagination URLs yourself! Here's an example response header from requesting the third page of [messages](sections/messages.md#messages):
Most collection APIs paginate their results. The first request returns up to 50 records. The Basecamp 3 API follows the [RFC5988 convention](https://tools.ietf.org/html/rfc5988) of using the `Link` header to provide URLs for the `next` page. Follow this convention to retrieve the next page of data—please don't build the pagination URLs yourself!
Here's an example response header from requesting the third page of [messages](sections/messages.md#messages):
```
Link: <https://3.basecampapi.com/999999999/buckets/2085958496/messages.json?page=4>; rel="next"
```
If the `Link` header is blank then that's the last page. We also provide the `X-Total-Count` header, which displays the total number of resources in the collection you are fetching.
If the `Link` header is blank, that's the last page. The Basecamp 3 API also provides the `X-Total-Count` header, which displays the total number of resources in the collection you are fetching.
Use HTTP caching
----------------
Using HTTP caching
------------------
You must make use of the HTTP freshness headers to speed up your app and lighten the load on our servers. Most API responses will include an `ETag` or `Last-Modified` header. When you first request a resource, store these values. On subsequent requests, submit them back to us as `If-None-Match` and `If-Modified-Since`, respectively. If the resource hasn't changed since your last request, you'll get a `304 Not Modified` response with no body, saving you the time and bandwidth of sending something you already have.
You must use HTTP freshness headers to speed up your application and lighten the load on our servers. Most API responses will include an `ETag` or `Last-Modified` header. When you first request a resource, store these values. On subsequent requests, submit them back to us as `If-None-Match` and `If-Modified-Since`, respectively. If the resource hasn't changed since your last request, you'll get a `304 Not Modified` response with no body, saving you the time and bandwidth of sending something you already have.
Handling errors
---------------
If Basecamp is having trouble, you might see a 5xx error. `500` means that the app is entirely down, but you might also see `502 Bad Gateway`, `503 Service Unavailable`, or `504 Gateway Timeout`. It's your responsibility in all of these cases to retry your request later.
If Basecamp is having trouble, you might get a 5xx error. `500` means that the application is entirely down, but `502 Bad Gateway`, `503 Service Unavailable`, or `504 Gateway Timeout` errors are also possible. In all of these cases, it's your responsibility to retry your request later.
Rate limiting
-------------
You can perform up to 50 requests per 10 second period from the same IP address for the same account. If you exceed this limit, you'll get a [429 Too Many Requests](http://tools.ietf.org/html/draft-nottingham-http-new-status-02#section-4) response for subsequent requests. Check the `Retry-After` header to see how many seconds to wait before retrying the request.
You can perform up to 50 requests per 10-second period from the same IP address for the same account. If you exceed this limit, you'll get a [429 Too Many Requests](http://tools.ietf.org/html/draft-nottingham-http-new-status-02#section-4) response for subsequent requests. Check the `Retry-After` header to learn how many seconds to wait before retrying the request.
We recommend baking 429 response handling in to your HTTP handling at a low level so your integration gracefully and automatically handles retries.
We recommend baking 429 response-handling in to your HTTP handling at a low level so your integration handles retries gracefully and automatically.
Rich text content
-----------------
Many resources, including messages, documents, and comments, represent their content as rich text in HTML. Rich text content may contain lists, block quotes, simple formatting, and inline attachments such as mentions, images, and files.
See the [Rich Text guide](sections/rich_text.md) for more details on working with HTML and attachments in rich text content.
See the [Rich text](sections/rich_text.md) section for more information about working with HTML and attachments in rich text content.
API endpoints
@@ -151,25 +158,25 @@ API endpoints
<!-- END API ENDPOINTS -->
List your integration
---------------------
Listing your application
------------------------
To add your service to our public list of Basecamp 3 integrations, head to https://github.com/basecamp/bc3-integrations and open a pull request.
To add your application to our public list of Basecamp 3 integrations, go to [https://github.com/basecamp/bc3-integrations](https://github.com/basecamp/bc3-integrations) and open a pull request.
Conduct
-------
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/basecamp/bc3-api/blob/master/CONDUCT.md). By participating in discussions about the Basecamp 3 API, you agree to abide by its terms.
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/basecamp/bc3-api/blob/master/CONDUCT.md). By participating in discussions about the Basecamp 3 API, you agree to abide by these terms.
License
-------
These API docs are licensed under [Creative Commons (CC BY-SA 4.0)](http://creativecommons.org/licenses/by-sa/4.0/). Please feel free to share (alike), remix, and distribute as you see fit.
These API docs are licensed under [Creative Commons (CC BY-SA 4.0)](http://creativecommons.org/licenses/by-sa/4.0/). Please share, remix, and distribute as you see fit.
---
If you have a specific feature request or if you found a bug, [please open a GitHub issue](https://github.com/basecamp/bc3-api/issues/new). We encourage forking these docs for local reference, and will happily accept pull request with improvements.
If you have a specific feature request or find a bug, [please open a GitHub issue](https://github.com/basecamp/bc3-api/issues/new). We encourage you to fork these docs for local reference and happily accept pull requests with improvements.
To talk with us and other developers about the API, [post a question on StackOverflow](http://stackoverflow.com/questions/ask) tagged `basecamp` or [open a support ticket](https://basecamp.com/support) if you need help from us directly.
To talk with us and other developers about the API, [post a question on StackOverflow](http://stackoverflow.com/questions/ask) tagged `basecamp`. If you need help from us directly, please [open a support ticket](https://basecamp.com/support).

0 comments on commit 66596fa

Please sign in to comment.