Expand description
§basecamp-sdk
The Rust client for the Basecamp API, generated from
the Smithy model in this repository’s spec/: every wire operation, every request and
response shape, and every operation’s retry, idempotency and pagination behaviour come from
openapi.json and behavior-model.json. The hand-written part is the plumbing they share —
authentication, retries, pagination, the two-hop download, OAuth — and the SPEC §18
merge-safe composites.
Project detail includes the optional logo; see project logo upload, removal and authenticated download.
[dependencies]
basecamp-sdk = "0.18"
tokio = { version = "1", features = ["full"] }§First call
use basecamp_sdk::{Client, Config};
#[tokio::main]
async fn main() -> Result<(), basecamp_sdk::Error> {
let client = Client::builder(Config::default())
.access_token(std::env::var("BASECAMP_TOKEN").expect("BASECAMP_TOKEN"))
.build()?;
let account =
client.for_account(std::env::var("BASECAMP_ACCOUNT_ID").expect("BASECAMP_ACCOUNT_ID"));
for project in account.projects().list(&Default::default()).await?.iter() {
println!("{} ({})", project.name, project.id);
}
Ok(())
}Services hang off an AccountClient: account.projects(),
account.todos(), account.cards() and so on, one per Basecamp service. Every method maps
to one operation of the model; the routes themselves are public data under
routes.
§Pagination
A paginated read answers a Page: the first page’s items plus the cursor
Basecamp handed out. Follow it a page at a time with
AccountClient::next_page, or collect the whole
collection with AccountClient::collect_all, which
stops at the client’s page cap and says so in ListMeta::truncated.
AccountClient::pages and
AccountClient::items walk lazily as streams; the item
stream ends with a usage error when the cap leaves a page unread. A read whose page is
an envelope around the collection gathers the same way: its generated shape implements
PageItems. A Link header pointing off the API origin
is refused, never followed.
§Errors
Every call answers a Result<T, Error>. The error carries the SPEC §6
record: a code, the message and hint, the HTTP status, whether the
call is retryable and the Retry-After the server named, the request id, and — on a 400/422 —
the structured field_errors.
§Retries
Retries follow SPEC §7’s three gates: the HTTP method’s own idempotency, the model’s
idempotent flag for a POST, and the operation’s declared retry_on statuses. Attempts are
min(client cap, operation max); a Retry-After header is honoured at every retried status,
and the local backoff is exponential with a 30 s ceiling and 100 ms of jitter. A 401 is
replayed once after the token provider refreshes, spending an attempt.
§Bring your own HTTP client
The SDK sends on one HttpClient. The reqwest feature (on by default)
ships one over rustls; with --no-default-features an application supplies its own.
§Features
| Feature | Default | What it adds |
|---|---|---|
reqwest | yes | The shipped HttpClient |
rustls-tls | yes | rustls for the shipped client |
native-tls | no | The platform TLS stack for the shipped client (additive) |
oauth | yes | oauth: PKCE, device grant, token exchange and refresh |
tracing | yes | One tracing span per operation |
event-feed | no | Reserved for the SPEC §23 connector |
§Environment variables
Only Config::from_env reads the environment; a Config built
literally reads no variable at all.
| Variable | Meaning | Only when |
|---|---|---|
BASECAMP_BASE_URL | The API origin (trailing / stripped) | Config::from_env() |
BASECAMP_TIMEOUT | Per-attempt timeout, in seconds | Config::from_env() |
BASECAMP_MAX_RETRIES | Total attempts per request, the first included | Config::from_env() |
BASECAMP_TOKEN and BASECAMP_ACCOUNT_ID appear in the examples only because the caller
reads them; the SDK never looks either up.
§Examples
examples/ holds one compiled program per README section — first_call, pagination,
errors and custom_http_client — and rs-test builds them all.
§Versioning
The crate follows the repository’s vX.Y.Z tags. Pre-1.0, a breaking change lands in a
0.MINOR release and an additive one in a 0.x.PATCH. The minimum supported Rust version
is 1.88 and is enforced in CI; it moves only in a 0.MINOR release, never past the
second-newest stable.
§Request construction policy
Request bodies, query-parameter structs and Config are plain pub structs with
Default and no #[non_exhaustive], so they are built literally —
CreateTodoRequestContent { content, ..Default::default() } — from any crate. A field
the model adds to one of them is therefore a source break, accepted as a 0.MINOR
release under the pre-1.0 policy. Response models and open enumerations (ErrorCode,
the model’s own string enums) are #[non_exhaustive]: a field or variant the API grows
is not a break. A shape that requests and responses share (QuestionSchedule) is a
request shape, and stays literal-constructible. Types with private fields (Error,
Client) need neither.
§Re-exported dependencies
chrono types are the model’s date and time representation and reqwest’s
builder is the shipped transport’s seam, so both crates are re-exported here at the
version this crate was built against: use basecamp_sdk::chrono and
basecamp_sdk::reqwest rather than guessing the matching minor. A minor bump of either
is a 0.MINOR release of this crate.
§Public traits
HttpClient, AuthStrategy, TokenProvider and Hooks are Send + Sync and
object-safe; the SDK holds each as an Arc<dyn Trait>. A method added to one of them
gets a default body, so implementing them stays source-compatible across 0.x.PATCH
releases.
Re-exports§
pub use auth::AuthStrategy;pub use auth::BearerAuth;pub use auth::StaticTokenProvider;pub use auth::TokenProvider;pub use client::AccountClient;pub use client::Client;pub use client::ClientBuilder;pub use client::Response;pub use config::Config;pub use download::DownloadResult;pub use error::Error;pub use error::ErrorCode;pub use hooks::Hooks;pub use http::HttpClient;pub use mentions::mention_markup;pub use mentions::mentioned_person_ids;pub use mentions::person_id_from_sgid;pub use mentions::with_mentions;pub use oauth::DeviceAuthorization;oauthpub use oauth::DeviceFlowError;oauthpub use oauth::DeviceFlowReason;oauthpub use oauth::DiscoveryOutcome;oauthpub use oauth::ExchangeRequest;oauthpub use oauth::FallbackReason;oauthpub use oauth::OAuthClient;oauthpub use oauth::Pkce;oauthpub use oauth::ProtectedResourceMetadata;oauthpub use oauth::RefreshRequest;oauthpub use oauth::RefreshingTokenProvider;oauthpub use oauth::SelectionError;oauthpub use oauth::SelectionFailure;oauthpub use oauth::ServerMetadata;oauthpub use oauth::Token;oauthpub use operation::Operation;pub use pagination::ListMeta;pub use pagination::ListResult;pub use pagination::Page;pub use pagination::PageItems;pub use types::AuthRoutableUrl;pub use types::Date;pub use types::DateChange;pub use types::DateTime;pub use types::FlexibleTime;pub use types::SensitiveString;pub use version::API_VERSION;pub use version::VERSION;pub use chrono;pub use reqwest;reqwest
Modules§
- auth
- SPEC §4: how credentials get onto a request, and how a refreshed token replaces a rejected one.
- client
- SPEC §3: the client, and the account-scoped client every service hangs off.
- config
- SPEC §2: what a client needs to know before it can talk to Basecamp.
- download
- SPEC §14: the two-hop download. An authenticated GET on the API origin answers a redirect to a signed storage URL, which is then fetched bare.
- error
- SPEC §6: the one error every call can answer with.
- hooks
- SPEC §12: what the SDK tells an application about the calls it makes.
- http
- The HTTP layer the client sends on, and the seam for replacing it.
- mentions
- Mention helpers over Basecamp rich text.
- metadata
- Per-operation behaviour from
behavior-model.json, generated from the model. - models
- The request and response types the Basecamp API speaks, generated from the model.
- oauth
oauth - SPEC §16: OAuth utilities — PKCE, resource-first discovery, the authorization-code exchange and refresh, and the RFC 8628 device grant.
- operation
- A request the client has not sent yet.
- pagination
- SPEC §8:
Link-header pagination. - retry
- SPEC §7: the three gates, the attempt budget and the backoff curve.
- route
- One API operation as data: its method, its path template and the behaviour the model
attaches to it. Every route the SDK knows lives in
crate::routes. - routes
- Every modelled route as public data, generated from the model.
- security
- SPEC §9: HTTPS enforcement, origin comparison and redaction.
- services
- The SPEC §18 hand-written composites, built over the generated wire operations. Nothing here touches the wire on its own.
- types
- The scalar types the model’s shapes are built from.
- url
- Recognizes Basecamp paths and URLs, as pasted from the web app or the API, and names the operations they refer to. Works offline, from the route table alone.
- version
- The SDK’s own version and the API contract it was generated against.
- webhooks
- SPEC §15: verifying a webhook delivery’s signature.
Constants§
- OPERATION_
COUNT - How many operations the model declares.