Present flat routes as canonical across all API documentation #373
Conversation
There was a problem hiding this comment.
Pull request overview
This PR transitions the Basecamp 4 API documentation to present flat routes (without /buckets/{id} prefix) as the canonical form for all endpoints. The legacy project-scoped routes are preserved for backward compatibility but moved to dedicated sections at the end of each file.
Changes:
- Added documentation for flat routes concept and usage patterns in README.md
- Updated all endpoint descriptions, cURL examples, and HTML comment markers across 34 section files to use flat routes
- Added "Legacy project-scoped routes" sections to each modified file with links to canonical endpoints
Reviewed changes
Copilot reviewed 35 out of 35 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Added flat routes section explaining the new canonical URL structure and updated key concept examples |
| sections/webhooks.md | Updated all endpoints to flat routes, added legacy section |
| sections/vaults.md | Updated all endpoints to flat routes, added legacy section |
| sections/uploads.md | Updated all endpoints to flat routes, added legacy section |
| sections/tools.md | Updated all endpoints to flat routes, added legacy section |
| sections/todosets.md | Updated all endpoints to flat routes, added legacy section |
| sections/todos.md | Updated all endpoints to flat routes, added legacy section |
| sections/todolists.md | Updated all endpoints to flat routes, added legacy section |
| sections/todolist_groups.md | Updated all endpoints to flat routes, added legacy section |
| sections/subscriptions.md | Updated all endpoints to flat routes, added legacy section |
| sections/schedules.md | Updated all endpoints to flat routes, added legacy section |
| sections/schedule_entries.md | Updated all endpoints to flat routes, added legacy section |
| sections/recordings.md | Updated all endpoints to flat routes, added legacy section |
| sections/questions.md | Updated all endpoints to flat routes, added legacy section |
| sections/questionnaires.md | Updated all endpoints to flat routes, added legacy section |
| sections/question_answers.md | Updated all endpoints to flat routes, added legacy section |
| sections/messages.md | Updated all endpoints to flat routes, added legacy section |
| sections/message_types.md | Updated all endpoints to flat routes, added legacy section |
| sections/message_boards.md | Updated all endpoints to flat routes, added legacy section |
| sections/inboxes.md | Updated all endpoints to flat routes, added legacy section |
| sections/inbox_replies.md | Updated all endpoints to flat routes, added legacy section |
| sections/forwards.md | Updated all endpoints to flat routes, added legacy section |
| sections/events.md | Updated all endpoints to flat routes, added legacy section |
| sections/documents.md | Updated all endpoints to flat routes, added legacy section |
| sections/comments.md | Updated all endpoints to flat routes, added legacy section |
| sections/client_visibility.md | Updated all endpoints to flat routes, added legacy section |
| sections/client_replies.md | Updated all endpoints to flat routes, added legacy section |
| sections/client_correspondences.md | Updated all endpoints to flat routes, added legacy section |
| sections/client_approvals.md | Updated all endpoints to flat routes, added legacy section |
| sections/chatbots.md | Updated all endpoints to flat routes, added legacy section |
| sections/card_tables.md | Updated all endpoints to flat routes, added legacy section |
| sections/card_table_steps.md | Updated all endpoints to flat routes, added legacy section |
| sections/card_table_columns.md | Updated all endpoints to flat routes, added legacy section |
| sections/card_table_cards.md | Updated all endpoints to flat routes, added legacy section |
| sections/campfires.md | Updated all endpoints to flat routes, added legacy section |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cd5ac846e1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Great improvement! Are there any considerable performance differences between the old and the new URL structure or is this purely 'cosmetic'? Also, thanks for keeping the old endpoints alive. Now we can upgrade the Ganttify integration to the new URL structure on our own pace. |
No performance difference.
Note this isn't live yet. I'm assessing whether we can swing it with 100% compatibility. The old URLs will be supported until the end of the Internet. |
|
I know. I just always stay on top of potential API changes of our integrations 😁 Glad to hear you guys take backwards compatibility serious! 🙏 |
Introduce a "Flat routes" section explaining that resources are accessed directly by ID without bucket/project prefix. Note exceptions where project-scoped routes are still required. Update "Making a request" example, pagination Link header, and key concepts to lead with flat forms.
Update todos, todolists, messages, comments, documents, uploads, schedule_entries, questions, question_answers, and vaults to present flat routes as canonical. Add legacy project-scoped routes section to each file.
Update card_table_cards, card_table_columns, card_table_steps, card_tables, todolist_groups, campfires, forwards, inbox_replies, and inboxes to present flat routes as canonical with legacy sections.
Flatten show endpoints for client approvals and correspondences. Index routes remain project-scoped (no flat index route exists). Add legacy sections to each file.
Update recordings, subscriptions, client_visibility, and events to present flat routes as canonical with legacy sections.
Update message_boards, todosets, schedules, and questionnaires to present flat routes as canonical with legacy sections.
Flatten show/update/destroy for chatbots and webhooks. Webhook index/create remain project-scoped (no flat route exists). Add exception note for chatbot integration endpoint which requires bucket-scoped URL due to access-key authentication.
Message types (categories) and dock tools do not have flat route equivalents in the API. Revert these to bucket-scoped endpoint paths. JSON response bodies are updated from doc_updater.
Summary
/buckets/{id}prefix) as the canonical form for API endpointsCommits
Test plan