Basecamp 3 API Essential Guide

What type of API does Basecamp 3 provide?

Basecamp 3 uses a REST-style API.

Key points:

• The API uses JSON for serialization and OAuth 2.0 for authentication.
• The API is described as "REST-style", indicating it follows REST principles but may not be a strictly RESTful API.
• Key characteristics of the Basecamp API:
  • Uses JSON for data exchange
  • Requires OAuth 2.0 for authentication
  • Uses pagination via Link and X-Total-Count headers
  • All API URLs end in .json
• The API is not compatible with older Basecamp Classic or Basecamp 2 APIs.

Best practices:

• Use OAuth 2.0 for authentication rather than basic auth
• Include proper Content-Type and Accept headers when making requests
• Paginate results using the provided Link header
• Use HTTPS for all API requests

In summary, Basecamp 3 uses a REST-style API with JSON payloads and OAuth 2.0 authentication. While not strictly RESTful, it follows many REST principles and conventions common to modern web APIs.

Does the Basecamp 3 API have webhooks?

Yes, the official Basecamp 3 API does have webhooks. Here are the key points about Basecamp 3 webhooks:

Webhook Support

• Basecamp 3 officially supports webhooks as part of its API.

Setting Up Webhooks

• Webhooks can be set up using the Webhooks API or directly within a Basecamp project.
• The payload URL for webhooks must use HTTPS.

Event Types

You can subscribe to the following types of events with Basecamp 3 webhooks:

• Todo creation
• Project creation
• Message creation
• Comment creation
• Schedule entry creation
• File upload
• Activity creation
• Person creation
• Todo-List creation
• Account creation
• Document creation

Webhook Payload

• When a subscribed event occurs, Basecamp will send a POST request to your specified payload URL with details about the event.

Best Practices

• Use a secret key to verify the authenticity of webhook requests from Basecamp.
• Handle potential retries and errors gracefully in your webhook endpoint.

Integration Possibilities

• Webhooks allow you to build custom integrations and automate workflows based on events in Basecamp 3.

It's important to note that while this information is based on the Basecamp 3 API, Basecamp has since released version 4. However, the webhook functionality appears to be similar across versions. Always refer to the most up-to-date official documentation for the latest information on Basecamp API capabilities.

Rate Limits and other limitations

Here are the key points about the API rate limits for the Basecamp 3 API:

Rate Limiting Details

• Basecamp uses a 429 Too Many Requests response when rate limits are exceeded.

• The Retry-After response header indicates how long to wait (in seconds) before retrying a rate-limited request.

• Multiple rate limits are in effect, including different limits for GET vs POST requests and per-second/hour/day limits.

• The rate limits are adjusted dynamically, so integrations need to handle them dynamically.

• As a general guideline, the first rate limit commonly encountered is 50 requests per 10 second period per IP address.

Key Considerations

• Integrations should plan ahead to gracefully handle rate limiting, especially at high traffic levels.

• The rate limits can change, so responding to them dynamically is essential.

• Using HTTP caching headers like ETag and If-None-Match can help reduce unnecessary requests and avoid hitting rate limits.

• Setting an identifiable User-Agent header is important, as requests without one are more tightly rate-limited.

Best Practices

• Implement exponential backoff when retrying rate-limited requests.

• Use the Retry-After header to determine how long to wait before retrying.

• Bake graceful handling of 429 responses into your integration from the beginning.

• Use HTTP caching to reduce unnecessary requests.

• Set an identifiable User-Agent header with your app name and contact info.

By following these guidelines and implementing proper rate limit handling, integrations can work smoothly with the Basecamp 3 API while respecting its usage limits.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the Basecamp API:

Current Version

The most recent version of the Basecamp API is the Basecamp 4 API. This is different from the previous Basecamp 3 API.

Key Points

• The Basecamp 4 API is not compatible with previous versions (Basecamp Classic API or Basecamp 2 API).

• It is a REST-style API that uses JSON for serialization and OAuth 2.0 for authentication.

• All API URLs end in .json to indicate they return JSON.

• The base URL for API requests is https://3.basecampapi.com/999999999/, where 999999999 is replaced with the account ID.

Changes from Previous Versions

Some notable changes in the Basecamp 4 API compared to previous versions include:

• OAuth 2.0 is required for authentication - Basic authentication is no longer supported.
• Pagination is performed via the Link and X-Total-Count headers.

API Documentation

The full documentation for the Basecamp 4 API can be found at: https://github.com/basecamp/bc3-api

Best Practices

• Use OAuth 2.0 for authentication.
• Include proper headers like Content-Type: application/json; charset=utf-8 when making POST or PUT requests.
• Follow the pagination links provided in the Link header rather than constructing pagination URLs manually.
• Handle 404 errors appropriately, as they may indicate deleted content, inactive accounts, or insufficient permissions.

In summary, the most recent version is the Basecamp 4 API, which introduces several changes from previous versions and requires developers to adapt their integration code accordingly.

How to get a Basecamp 3 developer account and API Keys?

Here's how you can get a developer account for Basecamp 3 to create an API integration:

1. Create a Basecamp account:

• Go to https://basecamp.com/
• Click on "Try it for free" to create a new account
• Fill in the required information and complete the registration process

2. Access the developer tools:

• Log in to your Basecamp account
• Go to https://launchpad.37signals.com/integrations

3. Create an OAuth application:

• Click on "Register another application"
• Fill in the application details form with the following information:
  • Name of your application
  • Your company's name
  • Your website URL
  • Products (choose the ones your company uses)
  • Redirect URI (where Basecamp will redirect users after authorization)

4. Save and get credentials:

• Click "Register this app" to create the OAuth application
• You'll be redirected to the application details page
• On this page, you'll find your Client ID and Client Secret

5. Use the OAuth application:

• Implement the OAuth authorization flow in your application
• This involves redirecting users to Basecamp's authorization endpoint and obtaining an access token
• Refer to Basecamp's API documentation for detailed instructions on implementing the OAuth flow and making API requests

What can you do with the Basecamp 3 API?

Based on the search results provided, here is a list of data models you can interact with using the Basecamp 3 API, along with what is possible for each:

Projects

• List all projects
• Create new projects
• Retrieve project details

People

• List people in an account or project
• Retrieve details about specific users

To-dos and To-do Lists

• Create, read, update, and delete to-dos
• Create and manage to-do lists
• Group to-do lists

Messages

• Create, read, update, and delete messages
• Interact with message boards

Documents

• Create, read, update, and delete documents

Comments

• Add comments to various objects (likely messages, to-dos, etc.)

Attachments

• Upload and manage file attachments

Events

• Manage events (likely related to schedules/calendars)

Schedules

• Create and manage schedules
• Add schedule entries

Chatbots

• Interact with chatbots (specific capabilities not detailed)

Inboxes

• Manage inboxes
• Add inbox replies

Uploads

• Upload files to Basecamp

Vaults

• Interact with vaults (likely for file storage)

Webhooks

• Set up and manage webhooks for real-time notifications

Additional Data Models:

• Campfires
• Card tables (including cards, columns, and steps)
• Client approvals and correspondences
• Questionnaires and questions
• Recordings
• Subscriptions
• Templates

Key Points:

• The API uses JSON for data exchange.
• Authentication is done via OAuth 2.0.
• Pagination is handled through Link and X-Total-Count headers.
• The API supports full CRUD (Create, Read, Update, Delete) operations for many data models.

Best Practices:

• Use proper authentication and include necessary headers in requests.
• Be aware of rate limiting and pagination when working with large datasets.
• Consult the official API documentation for detailed endpoints and request/response formats for each data model.

This list covers a wide range of Basecamp 3 features, allowing for comprehensive integration and interaction with the platform through its API.