Skip to content

Split REST API docs by document type and add Images#186

Merged
hackerwins merged 1 commit into
mainfrom
docs-rest-api-images-and-type-split
May 5, 2026
Merged

Split REST API docs by document type and add Images#186
hackerwins merged 1 commit into
mainfrom
docs-rest-api-images-and-type-split

Conversation

@hackerwins

@hackerwins hackerwins commented May 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

  • Reorganize developers/rest-api.md into Common (Documents, Images), Sheets-only (Tabs, Cells), and Docs-only (Document Content) sections so readers know which endpoints apply to which document type.
  • Add the missing Images section: POST/GET/DELETE /api/v1/workspaces/:wid/images[/imageId] with multipart upload constraints (10 MB, png/jpeg/gif/webp).
  • Add response-shape tables for Tabs (id, name, type, kind) and Cells (ref, value, formula, style) so readers don't have to guess what comes back.
  • Add a top-level coverage table (Sheet/Doc applicability) and call out the TYPE_MISMATCH 409 behavior up front.

Why

The page documented Tabs/Cells/Content side by side with no signal that Tabs/Cells reject doc documents and Content rejects sheets. The Images controller (packages/backend/src/api/v1/images.controller.ts) was completely undocumented despite being part of the public v1 surface used for image upload from both sheets and docs.

Test plan

  • pnpm verify:fast passes
  • Skim the rendered page (pnpm --filter @wafflebase/documentation dev) to confirm anchors and tables render correctly
  • Verify the cross-reference table matches actual controller behavior

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Reorganized REST API documentation for improved clarity
    • Added API Surface by Document Type reference matrix
    • Documented new Images endpoints (upload, retrieve, delete)
    • Expanded Sheets and Documents sections with detailed field definitions
    • Clarified type-specific endpoint behavior and HTTP 409 error guidance

@hackerwins @claude
Split REST API docs by document type and add Images section
6713a87 
The REST API page was missing the entire Images endpoint group and
gave no signal about which endpoints apply to sheet vs. doc documents.
Readers creating a doc had no way to know Tabs/Cells return 409, and
no documented path for image upload at all.

Reorganize into Common (Documents, Images), Sheets-only (Tabs, Cells),
and Docs-only (Document Content). Add a coverage table at the top and
response-shape tables for Tabs and Cells.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
@coderabbitai

coderabbitai Bot commented May 5, 2026 •
edited
Loading

Copy link
Copy Markdown
📝 Walkthrough

Walkthrough

The REST API documentation was reorganized with a new capability matrix by document type, expanded create operations (sheets and docs), added complete Images endpoints, enhanced Tabs and Cells field definitions, and clarified Document Content as docs-only with explicit TYPE_MISMATCH handling.

Changes

REST API Documentation Enhancements

Layer / File(s) Summary
API Surface Overview
packages/documentation/developers/rest-api.md		 Added "API Surface by Document Type" matrix showing which endpoints apply to sheets vs. docs, with HTTP 409 TYPE_MISMATCH callout for cross-endpoint calls.
Document Creation
packages/documentation/developers/rest-api.md		 Expanded "Create Document" section with explicit "Create a doc" subsection and example showing type: "doc" payload, while preserving default sheet behavior.
Images Endpoints
packages/documentation/developers/rest-api.md		 Added complete "Images" section documenting POST (multipart upload with size/type constraints), GET (image bytes with caching), and DELETE (returns { "deleted": true }) operations.
Sheet-Specific Fields
packages/documentation/developers/rest-api.md		 Expanded "Tabs (sheets only)" and "Cells (sheets only)" sections with field definitions tables and "Set Cell Value" request body shape (including value and formula fields).
Document Content Clarification
packages/documentation/developers/rest-api.md		 Added "Document Content (docs only)" section explicitly stating docs-only semantics, HTTP 409 TYPE_MISMATCH when called against sheets, and required blocks field table.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

A rabbit hops through docs so fine,
Sheets and docs now neatly align,
Images upload with care and grace,
Each endpoint finds its proper place, 🐰
REST API shines, oh what a sight!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title 'Split REST API docs by document type and add Images' directly reflects the main changes: reorganizing documentation by document type and documenting missing image endpoints.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs-rest-api-images-and-type-split

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions

github-actions Bot commented May 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Verification: verify:self

Result: ✅ PASS in 138.3s

Lane Status Duration
sheets:build ✅ pass 13.3s
docs:build ✅ pass 13.0s
verify:fast ✅ pass 70.5s
frontend:build ✅ pass 18.2s
verify:frontend:chunks ✅ pass 0.3s
backend:build ✅ pass 4.9s
cli:build ✅ pass 2.1s
verify:entropy ✅ pass 16.0s

Verification: verify:integration

Result: ✅ PASS

@codecov

codecov Bot commented May 5, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@hackerwins
hackerwins merged commit 3e41306 into main May 5, 2026
4 checks passed
@hackerwins
hackerwins deleted the docs-rest-api-images-and-type-split branch May 5, 2026 10:27
@hackerwins hackerwins mentioned this pull request May 11, 2026
Merged
6 tasks
hackerwins added a commit that referenced this pull request May 11, 2026
@hackerwins
Bump version to v0.4.0 (#211)
9fc2b1f 
Adds @wafflebase/slides as a third surface alongside Sheets and Docs,
plus 53-shape library (Phase 1+2), adjustment handles for 9 pilot
shapes (P3-A.1), live snap guides, align/distribute toolbar, themed
authoring, and layout-change UI. Also ships Sheets cell comments
(Phase B), docs peer-avatar caret jump, yorkie-js-sdk 0.7.8 upgrade,
and CLI/REST API improvements (docs export imageFetcher, expired
session refresh, REST docs split). Minor bump because slides is a
new top-level package.

Highlights: #184 #185 #186 #187 #188 #189 #190 #191 #192 #197 #198
#201 #202 #203 #204 #205 #206 #207 #209 #210
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@hackerwins