Login system api overhaul docs - #5
Conversation
- Introduced comprehensive API documentation for the Spoo.me URL shortening service. - Defined endpoints for creating, managing, and retrieving shortened URLs with detailed request and response schemas. - Included security definitions for API key and bearer token authentication. - Documented rate limits, authentication requirements, and usage guidelines for each endpoint. - Added tags for better organization of API functionalities: URL Shortening, URL Management, and Analytics.
…, and enhance rate limits section - Created a new documentation file for API Keys, detailing creation, management, and usage. - Updated the introduction to highlight the recommended API version and its base URL. - Revised the quickstart guide to focus on the v1 API, including examples for shortening URLs and retrieving statistics. - Enhanced the rate limits section to reflect new limits for the v1 API and provided a comparison with the legacy v0 API. - Added best practices and next steps for users to follow after learning about rate limits.
- Updated the Docker deployment guide to simplify prerequisites and installation steps. - Enhanced the quick start section with clearer instructions for cloning the repository and creating the .env file. - Improved the advanced configuration section, emphasizing the use of internal MongoDB and optional OAuth/webhook setups. - Added detailed steps for setting up JWT and OAuth authentication in the new authentication setup guide. - Revised the introduction to highlight API v1 features and their benefits. - Updated links to Discord support and community resources.
Zingzy
added
documentation
Reviewer's GuideThis PR completely revamps the Spoo.me documentation to support the new v1 API and streamline self-hosting, authentication, and API key workflows. It reorganizes navigation to separate v1 and legacy v0 material, adds detailed JWT/OAuth and API key guides, updates every code sample and rate-limit section to the v1 JSON format, and simplifies Docker and local-development instructions with concise quickstarts and updated environment configurations. Sequence diagram for API key authentication in v1 APIsequenceDiagram
actor User
participant "Spoo.me API"
User->>"Spoo.me API": POST /api/v1/shorten (Authorization: Bearer spoo_API_KEY)
"Spoo.me API"->>"MongoDB Database": Store shortened URL
"Spoo.me API"->>User: Return full response (short_url, alias, owner_id, etc.)
Sequence diagram for OAuth login and dashboard accesssequenceDiagram
actor User
participant "Web UI"
participant "OAuth Provider"
User->>"Web UI": Click login (Google/GitHub/Discord)
"Web UI"->>"OAuth Provider": Redirect for authentication
"OAuth Provider"->>"Web UI": Return user info (JWT)
"Web UI"->>User: Show dashboard
ER diagram for API key scopes and user relationshiperDiagram
USER ||--o{ API_KEY : owns
API_KEY }o--|| SCOPE : grants
USER {
id string
email string
name string
}
API_KEY {
id string
name string
scopes string[]
owner_id string
revoked bool
expires_at int
}
SCOPE {
name string
description string
}
Class diagram for API key and authentication entities in v1 APIclassDiagram
class APIKey {
+id: string
+name: string
+description: string
+scopes: string[]
+created_at: int
+expires_at: int
+revoked: bool
+owner_id: string
}
class JWT {
+token: string
+issuer: string
+audience: string
+user_id: string
+expires_at: int
+scopes: string[]
}
class User {
+id: string
+email: string
+name: string
+oauth_provider: string
+api_keys: APIKey[]
}
User "1" -- "*" APIKey : owns
User "1" -- "*" JWT : sessions
Class diagram for v1 Shortened URL response structureclassDiagram
class ShortenedURL {
+alias: string
+short_url: string
+long_url: string
+owner_id: string
+created_at: int
+status: string
+private_stats: bool
+max_clicks: int
+expire_after: int
+block_bots: bool
+password: string
}
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughThis PR introduces API v1 with a full OpenAPI spec, promotes API v0 to legacy, adds API key and authentication docs, rewrites quickstart and rate-limit docs for v1, expands self‑hosting authentication and environment guidance, restructures navigation, updates invite links, and pins Node.js to version 24 via Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant API as Spoo.me API v1
participant Auth as Auth Service
participant DB as Database
participant Cache as Redis
rect rgba(52,152,219,0.06)
Note over Client,API: Authenticated shorten flow (API v1)
Client->>Auth: Create or provide API Key / JWT
Client->>API: POST /api/v1/shorten (Authorization: Bearer / spoo_*)
API->>Auth: Validate token/key
Auth-->>API: Validation result
alt valid
API->>DB: Persist shortened URL
DB-->>API: URL created
API-->>Client: 201 ShortenedUrlResponse
else invalid
API-->>Client: 401 ErrorResponse
end
end
rect rgba(155,89,182,0.04)
Note over Client,API: Anonymous stats (lower limits)
Client->>API: GET /api/v1/stats?scope=anon&short_code=xyz
API->>Cache: Fetch cached stats
alt cache hit
Cache-->>API: cached data
else cache miss
API->>DB: Query stats
DB-->>API: stats
API->>Cache: Update cache
end
API-->>Client: UrlStatisticsV1Response
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey there - I've reviewed your changes - here's some feedback:
Blocking issues:
- Identified a Private Key, which may compromise cryptographic security and sensitive data encryption. (link)
- Identified a Private Key, which may compromise cryptographic security and sensitive data encryption. (link)
- Identified a Private Key, which may compromise cryptographic security and sensitive data encryption. (link)
General comments:
- This PR introduces extensive changes across authentication, deployment, and API reference—consider splitting it into smaller, focused PRs (e.g., one for v1 docs, one for self-hosting, one for API reference) to simplify review.
- Several api-reference files appear deleted or empty (e.g., create-emoji-urls, get-url-statistics); please ensure all v1 endpoint docs are fully populated so the reference section remains complete.
- Don’t forget to update your navigation config (docs.json or sidebar settings) to include the new authentication and API-keys pages so they show up in the docs sidebar.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- This PR introduces extensive changes across authentication, deployment, and API reference—consider splitting it into smaller, focused PRs (e.g., one for v1 docs, one for self-hosting, one for API reference) to simplify review.
- Several api-reference files appear deleted or empty (e.g., create-emoji-urls, get-url-statistics); please ensure all v1 endpoint docs are fully populated so the reference section remains complete.
- Don’t forget to update your navigation config (docs.json or sidebar settings) to include the new authentication and API-keys pages so they show up in the docs sidebar.
## Individual Comments
### Comment 1
<location> `rate-limits.mdx:103-109` </location>
<code_context>
+
+| Endpoint | Authenticated | Anonymous | Notes |
+|----------|--------------|-----------|-------|
+| `POST /api/v1/shorten` | 60/min, 5000/day | 20/min, 1000/day | v1 API |
+| `POST /` | - | 10/min, 100/hr, 500/day | v0 API (legacy) |
+| `POST /emoji` | - | 10/min, 100/hr, 500/day | v0 API (legacy) |
+
+### URL Management
</code_context>
<issue_to_address>
**suggestion:** The endpoint table mixes v1 and v0 endpoints, which may confuse users.
Consider separating v1 and v0 endpoints into distinct tables or adding clear visual cues and notes to differentiate API versions.
```suggestion
### URL Shortening
#### v1 API Endpoints
| Endpoint | Authenticated | Anonymous | Notes |
|----------|--------------|-----------|-------|
| `POST /api/v1/shorten` | 60/min, 5000/day | 20/min, 1000/day | v1 API |
#### v0 API Endpoints (Legacy)
<Note>
The following endpoints are part of the legacy v0 API. They do not support authentication and have lower rate limits.
</Note>
| Endpoint | Authenticated | Anonymous | Notes |
|----------|--------------|-----------|-------|
| `POST /` | - | 10/min, 100/hr, 500/day | v0 API (legacy) |
| `POST /emoji` | - | 10/min, 100/hr, 500/day | v0 API (legacy) |
```
</issue_to_address>
### Comment 2
<location> `rate-limits.mdx:125-126` </location>
<code_context>
+| Endpoint | Authenticated | Anonymous | Notes |
+|----------|--------------|-----------|-------|
+| `GET /api/v1/stats` | 60/min, 5000/day | 20/min, 1000/day | Public URLs only for anon |
+| `POST /stats/{code}` | - | Not limited | v0 API (legacy) |
+| `POST /export/{code}/{format}` | - | Not limited | v0 API (legacy) |
+
+## Authentication & Rate Limits
</code_context>
<issue_to_address>
**question:** Legacy endpoints are described as 'Not limited', which may be misleading.
Please clarify if 'Not limited' means no rate limits at all, or if there are backend or global restrictions that apply to these legacy endpoints.
</issue_to_address>
### Comment 3
<location> `self-hosting/setting-up-authentication.mdx:64-65` </location>
<code_context>
-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhki...\n-----END PRIVATE KEY-----"
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
</code_context>
<issue_to_address>
**security (private-key):** Identified a Private Key, which may compromise cryptographic security and sensitive data encryption.
*Source: gitleaks*
</issue_to_address>
### Comment 4
<location> `self-hosting/setting-up-authentication.mdx:230-231` </location>
<code_context>
-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
</code_context>
<issue_to_address>
**security (private-key):** Identified a Private Key, which may compromise cryptographic security and sensitive data encryption.
*Source: gitleaks*
</issue_to_address>
### Comment 5
<location> `self-hosting/local-development.mdx:183-184` </location>
<code_context>
-----BEGIN PRIVATE KEY-----\nYour-Private-Key-Here\n-----END PRIVATE KEY-----"
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
</code_context>
<issue_to_address>
**security (private-key):** Identified a Private Key, which may compromise cryptographic security and sensitive data encryption.
*Source: gitleaks*
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
README.md (1)
25-25: Use hyphen in compound adjective.Line 25 contains "3x higher limits with authentication" as part of a bulleted feature. To follow standard grammar, use a hyphen when a compound adjective precedes a noun: "3x-higher limits" or rephrase as "3x higher rate limits."
- **Rate Limiting Guide** - 3x higher limits with authentication + **Rate Limiting Guide** - 3x-higher limits with authenticationself-hosting/docker-deployment.mdx (1)
134-143: Reduce excessive punctuation for a more professional tone.Line 143 contains "No manual database setup, no configuration files, no complex installation steps!" followed by other content with multiple exclamation marks nearby. Consider reducing the number of exclamation marks to maintain a professional, credible tone in technical documentation.
- No manual database setup, no configuration files, no complex installation steps! + No manual database setup, no configuration files, no complex installation steps.openapi-v1.json (1)
1021-1025: Add maxItems constraint to array parameters per OpenAPI best practices.Line 1021-1025 defines the
group_byparameter as an array without a maximum length constraint. The Checkov security check (CKV_OPENAPI_21) recommends adding amaxItemsconstraint to prevent potential resource exhaustion via unbounded arrays.The
group_byparameter lists 7 valid dimensions (time, browser, os, country, city, referrer, short_code). Consider adding"maxItems": 7to the schema definition to bound the array size."group_by": { "type": "array", "items": { "type": "string" } + "maxItems": 7 }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (20)
.nvmrc(1 hunks)README.md(2 hunks)api-keys.mdx(1 hunks)api-reference/analytics/get-url-statistics.mdx(0 hunks)api-reference/data-export/export-url-data.mdx(0 hunks)api-reference/shorten-url.mdx(1 hunks)api-reference/url-shortening/create-emoji-urls.mdx(0 hunks)api-reference/url-shortening/shorten-long-urls.mdx(0 hunks)docs.json(2 hunks)introduction.mdx(3 hunks)openapi-v1.json(1 hunks)quickstart.mdx(9 hunks)rate-limits.mdx(2 hunks)self-hosting/cloud-deployment.mdx(3 hunks)self-hosting/docker-deployment.mdx(1 hunks)self-hosting/introduction.mdx(2 hunks)self-hosting/local-development.mdx(4 hunks)self-hosting/setting-up-authentication.mdx(1 hunks)tools/python-library.mdx(1 hunks)tools/spoobot.mdx(1 hunks)
💤 Files with no reviewable changes (4)
- api-reference/analytics/get-url-statistics.mdx
- api-reference/url-shortening/shorten-long-urls.mdx
- api-reference/data-export/export-url-data.mdx
- api-reference/url-shortening/create-emoji-urls.mdx
🧰 Additional context used
🪛 Checkov (3.2.334)
openapi-v1.json
[medium] 1021-1025: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🪛 Gitleaks (8.29.0)
self-hosting/setting-up-authentication.mdx
[high] 183-184: Identified a Private Key, which may compromise cryptographic security and sensitive data encryption.
(private-key)
self-hosting/local-development.mdx
[high] 183-184: Identified a Private Key, which may compromise cryptographic security and sensitive data encryption.
(private-key)
🪛 LanguageTool
api-reference/shorten-url.mdx
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: --- openapi: POST / ---
(QB_NEW_DE)
self-hosting/docker-deployment.mdx
[style] ~143-~143: Using many exclamation marks might seem excessive (in this case: 5 exclamation marks for a text that’s 3114 characters long)
Context: ...ion files, no complex installation steps! ## Production Deployment Want to depl...
(EN_EXCESSIVE_EXCLAMATION)
README.md
[uncategorized] ~25-~25: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...thentication and scoped permissions - Rate Limiting Guide - 3x higher limits with authent...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Sourcery review
🔇 Additional comments (45)
tools/python-library.mdx (1)
362-362: LGTM — Discord link updated correctly.The URL update from the old Discord invite to the new spoo.me domain alias is consistent with changes across other documentation files.
tools/spoobot.mdx (1)
206-206: LGTM — Discord link updated for consistency.The URL is now aligned with other documentation files and the new spoo.me domain alias pattern.
.nvmrc (1)
1-1: LGTM — Node.js 24 pinned correctly.Version pinning is appropriate for standardizing the development environment across the documentation build pipeline.
self-hosting/local-development.mdx (4)
183-184: Flag: Clarify that example JWT keys are placeholders, not real credentials.Static analysis (Gitleaks) is correctly flagging the RSA key format in the example configuration. While the keys are clearly marked with
...placeholders, it would help to explicitly label them as examples to reduce false positives in CI/CD scanning and to clearly communicate that users must generate their own keys.Consider updating:
-JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour-Private-Key-Here\n-----END PRIVATE KEY-----" -JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nYour-Public-Key-Here\n-----END PUBLIC KEY-----" +# Example only - generate your own RSA key pair using the steps in setting-up-authentication.mdx +JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYOUR_GENERATED_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----" +JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nYOUR_GENERATED_PUBLIC_KEY_HERE\n-----END PUBLIC KEY-----"Or better yet, reference the auth setup guide more explicitly:
-JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour-Private-Key-Here\n-----END PRIVATE KEY-----" -JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nYour-Public-Key-Here\n-----END PUBLIC KEY-----" +# See /self-hosting/setting-up-authentication for key generation instructions +JWT_PRIVATE_KEY="<your-generated-private-key>" +JWT_PUBLIC_KEY="<your-generated-public-key>"
33-35: LGTM — New prerequisites and cross-references are well-documented.The links to MongoDB setup, authentication setup, and webhook creation provide clear guidance for users and align with the broader restructuring of self-hosting documentation.
213-219: LGTM — Practical UX guidance for environment setup.The
.env.examplecopy tip and.gitignorewarning are helpful for users setting up their development environment locally.
259-278: LGTM — Clear delineation of public vs. authenticated feature testing.Separating testing steps into "Public Features" and "Authenticated Features" sections helps users understand the scope of each test and the new v1 authentication model.
api-reference/shorten-url.mdx (1)
1-3: LGTM — OpenAPI reference frontmatter is correct.The YAML frontmatter is valid for documentation generation systems that render OpenAPI specifications. The LanguageTool grammar flag is a false positive (the tool does not understand YAML/OpenAPI syntax).
self-hosting/setting-up-authentication.mdx (4)
64-65: Flag: Clarify that example JWT keys are placeholders and must be generated.Static analysis flags these lines as potential private keys. While the keys are clearly marked with example syntax (
\nMIIEvgIBADANBgkqhki...\n), explicitly labeling them as "EXAMPLE ONLY" or referencing the key generation section above would reduce CI/CD false positives and reinforce that users must generate their own keys.Consider:
-JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhki...\n-----END PRIVATE KEY-----" -JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhki...\n-----END PUBLIC KEY-----" +# EXAMPLE ONLY - Use the keys you generated in the "Generate RSA Key Pair" section above +JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n<your-generated-key-here>\n-----END PRIVATE KEY-----" +JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n<your-generated-key-here>\n-----END PUBLIC KEY-----"
22-49: LGTM — Clear and secure RSA key generation instructions.The OpenSSL commands are correct and the step-by-step structure guides users through generating a proper 2048-bit RSA key pair for JWT signing.
75-212: LGTM — Comprehensive OAuth provider setup guidance.The step-by-step instructions for Google, GitHub, and Discord OAuth are clear, current, and follow security best practices (e.g., creating separate apps per provider, using appropriate redirect URIs for local vs. production).
273-312: LGTM — Practical troubleshooting section addresses common issues.The troubleshooting section covers real-world gotchas (redirect URI mismatch, JWT verification, cookies, OAuth visibility) and provides actionable solutions that will help users debug configuration issues.
api-keys.mdx (5)
7-13: LGTM — Clear overview positioning API keys within v1 authentication landscape.The note about v1-only availability is important and well-placed for users understanding the relationship to legacy v0.
40-55: LGTM — Scope documentation provides clear permission model.The scope table clearly maps permissions to affected endpoints, and the least-privilege tip encourages secure practices.
75-107: LGTM — Usage examples are practical and secure.The curl examples use realistic key format (spoo_ prefix) without exposing real credentials, and Bearer token format is clearly demonstrated.
128-148: LGTM — Security best practices follow industry standards.Storage in environment variables, least privilege approach, rotation guidance, and .gitignore warnings align with security best practices for API key management.
202-213: LGTM — Mermaid diagram effectively illustrates key lifecycle.The lifecycle visualization helps users understand the states and transitions of API keys in the system.
self-hosting/cloud-deployment.mdx (3)
12-13: LGTM — Authentication setup added as prerequisite.The link to the new
/self-hosting/setting-up-authenticationguide makes the dependency clear and guides users to comprehensive setup instructions before deployment.
75-107: LGTM — New "Authentication Variables" section clearly separates v1 requirements.The separate section for authentication variables with clear "required for v1 API" notes helps users understand which variables enable new functionality. References to the detailed setup guide are appropriate.
123-125: LGTM — Practical tip reduces setup friction for users.Communicating that users can deploy with minimal variables and add OAuth providers later via environment settings is helpful for users wanting to iterate incrementally.
README.md (2)
9-15: Clearly distinguish v0 features as legacy.The feature list properly marks v0-specific features with "(v0 legacy)" designation, which is good for readers. This aligns well with the PR's goal of positioning v1 as primary.
17-19: Base URLs effectively communicate v1 recommendation.The side-by-side presentation of v1 (Recommended) and v0 (Legacy) is clear and helps developers choose the right endpoint immediately.
self-hosting/introduction.mdx (2)
18-59: Architecture diagram clearly communicates API v1 structure.The mermaid diagram effectively visualizes the versioned API flow, authentication paths, and data layer. The diagram successfully shows:
- API version routing (v1, v0, Web UI)
- Authentication decision tree (JWT/API Key vs Anonymous)
- Database and cache interactions
- Analytics engine integration
This is a significant improvement for self-hosting documentation clarity.
137-159: Feature organization properly positions v1 capabilities.The separation of API v1, Legacy v0, and Web Dashboard features is clear and helps self-hosters understand what functionality is available at each tier. The categorization aligns well with the PR's v1-first approach.
introduction.mdx (2)
16-26: Base URLs properly emphasize v1 adoption path.The explicit separation and labeling of API v1 (Recommended) and API v0 (Legacy) is excellent for guiding developers to the current best practice. The formatting makes it easy to spot the recommended endpoint.
54-87: Quick Start cards reflect a cohesive v1 workflow.The progression from "Create API Key" → "Shorten URLs" → "Manage URLs" → "Advanced Analytics" is logical and supports the documented v1 feature set. The card structure guides new users through a realistic first-use journey.
self-hosting/docker-deployment.mdx (3)
7-11: Docker deployment guide is user-focused and actionable.The rewrite significantly improves clarity by:
- Leading with the value proposition ("easiest and fastest")
- Emphasizing zero configuration for databases
- Separating quick start from advanced topics
- Making optional enhancements (Auth, webhooks) clearly optional
This is a major improvement over a more technical-first approach.
81-132: Four-step quick start is well-paced and achievable.The condensed quick start strikes a good balance:
- Clone → .env →
docker-compose up -d→ Access provides a complete mental model- Accordion for OAuth/webhooks prevents prerequisite creep
- Info box about first-run timing sets proper expectations
- Step titles are action-oriented
This structure will significantly reduce setup friction for new users.
145-256: Production deployment guidance provides realistic upgrade path.The section properly addresses the jump from local development to production by:
- Recommending managed databases (MongoDB Atlas) with clear benefits
- Providing example environment variable configuration
- Including optional Nginx reverse proxy setup for custom domains and SSL
- Offering Let's Encrypt automation guidance via Accordion
This transforms local Docker setup into a credible path toward production.
rate-limits.mdx (3)
9-100: Rate limit restructuring clearly communicates authentication benefit.The reorganization around API v1 with authentication effectively shows the 3x improvement (20 → 60 req/min) that authentication provides. Key strengths:
- Color-coded cards (green for authenticated, orange for anonymous, red for legacy) provide quick visual scanning
- Explicit "3x more requests" tip in line 65-67 creates clear call-to-action
- Legacy v0 rates prominently warn users with a red card and migration advisory
- Separation of v1 and v0 prevents confusion
This structure will effectively guide users toward authentication adoption.
101-127: Endpoint-level rate limit tables provide necessary specificity.The three endpoint tables (URL Shortening, URL Management, Analytics) effectively communicate:
- Which endpoints are available in v1 vs v0
- Authentication requirements per endpoint
- Exact rate limits at endpoint granularity
- That URL Management endpoints require authentication
This level of detail is crucial for developers integrating with the API.
128-174: Authentication accordion trio clearly explains rate limit mechanics.The three accordion sections (API Key, JWT, Anonymous) effectively communicate the cost/benefit of each authentication method and provide usage examples. This structure helps developers make informed choices about their integration approach.
quickstart.mdx (4)
7-11: Info block clearly communicates anonymous mode and authentication trade-off.The info block at lines 9-11 sets proper expectations: users can start without registration, but API keys unlock higher rate limits and advanced features. This balances ease-of-use with motivation to authenticate.
13-66: Step 1 code examples are properly updated to v1 API.All three language examples (cURL, Python, JavaScript) correctly demonstrate:
- Correct v1 endpoint:
https://spoo.me/api/v1/shorten- JSON Content-Type header (not form-encoded)
- Correct field name:
long_url(noturl)- Expected v1 response shape with all required fields
The transition from form-encoded to JSON payload is properly explained and demonstrated.
132-162: Stats endpoint correctly uses v1 anonymous scope pattern.The Step 3 examples correctly demonstrate:
- New v1 endpoint:
GET /api/v1/stats- Required
scope=anonparameter for anonymous accessshort_codeparameter for targeting specific URL- Correct response parsing:
stats['summary']['total_clicks']andstats['summary']['unique_clicks']- Note explaining public URL limitation is clear
This properly guides users to the v1 stats pattern.
276-302: Error handling functions are consistent and properly updated.Both Python (
safe_shorten_url) and JavaScript (safeShortenerUrl) functions:
- Use correct v1 endpoint and JSON payload
- Handle 201 (Created) status code correctly
- Include rate limit (429) and generic error handling
- Accept optional parameters via kwargs/options
- Return short_url on success, None/null on failure
The function signatures are consistent across languages and reflect v1 requirements.
Also applies to: 305-337
openapi-v1.json (6)
1-44: OpenAPI specification provides solid foundation for v1 API documentation.The specification header, servers, security schemes, and tags are well-structured:
- Clear versioning (v1.0.0) and description
- Production server correctly points to
/api/v1- Security schemes properly document JWT bearer tokens and API key format (
spoo_*)- Operation tags align with documentation structure (URL Shortening, URL Management, Analytics)
This provides a strong foundation for code generation and API exploration tools.
46-183: POST /shorten operation is comprehensive with clear rate limit guidance.The operation includes:
- Detailed description with authentication options, rate limits, and consequences of anonymous usage
- Well-documented request schema with constraints (long_url required, alias pattern validation, password minimum length, etc.)
- Example values for all parameters
- Complete response schemas (201, 400, 401, 403, 409, 429)
- Clear documentation of anonymous vs authenticated behavior
The extensive inline documentation will help developers understand both what the endpoint does and the implications of different usage patterns.
184-412: GET /stats operation handles complex filtering with clear documentation.The operation successfully documents:
- Two distinct usage modes: anonymous (scope=anon) and authenticated (scope=all)
- Flexible filtering via both JSON object and individual query parameters
- Example values for both filtering methods
- Rate limiting differences between authenticated and anonymous
- Clear limitation: anonymous users can only access public URLs
The dual filtering approach (Method 1: JSON filters vs Method 2: individual parameters) provides flexibility while maintaining clarity.
414-571: GET /urls operation provides comprehensive list management interface.The operation includes:
- Pagination (page, pageSize with limits)
- Sorting (sortBy with enum options, sortOrder)
- Advanced filtering via JSON filter parameter
- Filter examples covering common use cases
- Complete response schema with pagination metadata
This level of detail enables developers to build effective URL management interfaces.
573-825: PATCH and DELETE operations properly document URL management consequences.Both operations include:
- Clear ownership requirements (can only modify/delete own URLs)
- Detailed descriptions of update/delete semantics
- For DELETE: prominent warning about irreversibility and data loss
- For PATCH: documentation of nullable fields for removing settings
- Complete error scenarios (401, 403, 404, 409, 429)
The DELETE documentation's emphasis on permanence and suggestion to use INACTIVE status instead is particularly good UX guidance.
941-1275: Component schemas are complete and well-structured.The schemas properly define:
- Security schemes with clear format documentation
- Error and success response shapes
- Request/response bodies with nullable fields where appropriate
- Examples for complex types
- Proper use of refs for schema reusability
The separation of
ApiKeyResponse(with full token shown at creation) andApiKeyInfo(without token, for listing) is particularly good security practice.docs.json (3)
15-15: Navigation structure effectively positions API v1 as primary.The reorganization achieves several important goals:
- Moves "api-keys" into Getting Started (top-level prominence for authentication)
- Renames and reorganizes API Reference to "API v1 Reference" with three logical groups
- Uses openapi-v1.json reference (aligns with new spec file)
- Three sub-groups (URL Shortening, URL Management, Analytics) match OpenAPI operation tags
This structure guides new users toward modern v1 patterns while making authentication discoverable early.
Also applies to: 18-46
48-74: Legacy API v0 reference is appropriately positioned.The explicit "(Legacy)" label and separate OpenAPI reference (openapi-v0.json) clearly communicate deprecation status while preserving documentation for existing users who may still be using v0. Placement after v1 Reference in navigation further emphasizes the recommended upgrade path.
85-85: New authentication page in self-hosting supports v1 feature adoption.Adding "self-hosting/setting-up-authentication" in the self-hosting section is logical for users setting up their own instances and needing to configure authentication (OAuth providers, JWT, API key management) to unlock v1 features.
Verify that the
self-hosting/setting-up-authentication.mdxfile exists and is properly documented with setup instructions for authentication configuration. If this file is new to the PR, confirm it contains guidance on OAuth setup, JWT configuration, and API key management that aligns with the self-hosting Docker deployment guide.
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs.json(1 hunks)openapi-v1.json(1 hunks)
🧰 Additional context used
🪛 Checkov (3.2.334)
openapi-v1.json
[medium] 1272-1276: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Sourcery review
🔇 Additional comments (10)
docs.json (4)
53-80: API v0 Reference (Legacy) designation is clear and consistent.The renaming to include "(Legacy)" and separate OpenAPI spec (
openapi-v0.json) effectively communicates that v0 is deprecated. Ensureopenapi-v0.jsonexists and accurately reflects the v0 endpoint surface.
13-21: All referenced Getting Started pages exist.Verification confirms that
introduction.mdx,quickstart.mdx,api-keys.mdx, andrate-limits.mdxare all present in the repository. The navigation configuration in docs.json is properly aligned with existing files.
90-107: Self-hosting authentication guide verified—file exists.The new
self-hosting/setting-up-authentication.mdxfile is present and properly referenced in docs.json at line 95. The addition is valid and well-positioned in the self-hosting documentation flow.
22-52: API v1 Reference structure verified and correct.All endpoints referenced in docs.json are present in openapi-v1.json. The grouping of URL Shortening, URL Management, and Analytics properly organizes the seven endpoints with appropriate icons. No issues found.
openapi-v1.json (6)
1-22: OpenAPI v1 metadata is complete and well-documented.The specification clearly identifies this as v1 with accurate server URL and comprehensive contact/license information. The description appropriately highlights key v1 features.
1193-1206: Security schemes are well-defined with dual authentication support.The apiKey (spoo_* format) and bearerAuth (JWT) schemes appropriately support both API client and user authentication. The use of bearer token format for both is consistent, though the custom spoo_* format for API keys is clearly documented.
46-183: POST /shorten endpoint is comprehensive with clear security and rate-limit guidance.The endpoint properly documents anonymous vs authenticated workflows, includes all essential parameters with validation rules, and provides detailed error responses. The extensive description about rate limits and account-linkage consequences for anonymous users is particularly helpful.
184-349: GET /stats endpoint has exceptionally thorough parameter documentation.The dual-method filtering approach (JSON and individual parameters) provides flexibility for different client preferences. The case-sensitivity warnings and multiple examples significantly reduce implementation errors. Rate limit differentiation between authenticated/anonymous access is clearly specified.
414-663: GET /export endpoint appropriately implements rate-limiting and multi-format support.Lower rate limits (half of /stats) correctly reflect the resource cost of export generation. Multiple response content types are properly defined. The inclusion of a 500 error for export generation failures is appropriate for this complex operation.
665-1190: URL management endpoints are well-designed with proper ownership/scope checks.The GET /urls endpoint supports flexible filtering and pagination. The PATCH /urls/{url_id} properly documents that null values remove optional settings. The DELETE endpoint includes important warnings about irreversibility. The separate PATCH /urls/{url_id}/status convenience endpoint is useful, though documentation could clarify when to use it vs the main PATCH endpoint.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
openapi-v1.json (2)
1272-1276: Add maxItems constraint to UrlStatisticsV1Response.group_by array (duplicate issue).The
group_byarray lacks a maximum item constraint. Per Checkov CKV_OPENAPI_21 and previous review feedback, arrays should definemaxItemsto prevent unbounded arrays and resource exhaustion. The documentation mentions seven supported dimensions (time, browser, os, country, city, referrer, short_code).Apply this diff to add the constraint:
"group_by": { "type": "array", + "maxItems": 7, "items": { "type": "string" } },
1446-1524: Orphaned API key schemas—add endpoints or remove unused definitions (duplicate issue).The
ApiKeyResponseandApiKeyInfoschemas (lines 1446–1524) are defined but unreferenced by any endpoint. Per the PR objectives, API key management is a core feature of v1, yet no paths exist for creating, listing, or managing API keys (e.g.,POST /api-keys,GET /api-keys,DELETE /api-keys/{key_id}).Either add API key management endpoints that reference these schemas, or remove them to keep the specification lean.
To resolve, add paths such as:
"/api-keys": { "post": { "summary": "Create API Key", "operationId": "createApiKeyV1", "tags": ["API Keys"], "security": [{"bearerAuth": []}], "requestBody": {...}, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ApiKeyResponse"} } } } } }, "get": { "summary": "List API Keys", "operationId": "listApiKeysV1", ... } }, "/api-keys/{key_id}": { "delete": {...} }Alternatively, remove the
ApiKeyResponseandApiKeyInfoentries fromcomponents/schemasif API key endpoints are documented elsewhere or not yet implemented.
🧹 Nitpick comments (3)
openapi-v1.json (3)
88-92: Document password validation pattern in schema.The request body description for
passwordspecifies validation rules ("must contain a letter and a number and a special character either '@' or '.' and cannot be consecutive"), but the schema only enforcesminLength: 8. Without apatternproperty, client validation is imprecise and may diverge from server-side validation.Consider adding a
patternproperty to enforce these rules at the schema level:"password": { "type": "string", "minLength": 8, "pattern": "^(?=.*[a-zA-Z])(?=.*\\d)(?=.*[@.]).*$", "description": "Password to protect the shortened URL. Minimum 8 characters long, must contain a letter, a number, and either '@' or '.' character, and cannot be consecutive." }This clarifies the contract for API consumers and enables client-side validation.
73-79: Add minLength constraint to long_url field.The
long_urlproperty definesmaxLength: 2048but nominLength. Add a minimum length (e.g., 1 or higher) to reject empty or malformed URLs explicitly."long_url": { "type": "string", "format": "uri", + "minLength": 1, "maxLength": 2048, "description": "The original URL to shorten. Must start with http:// or https://", "example": "https://example.com/very/long/url" },
253-260: Clarify group_by parameter type: is it string or array?The
/statsGET endpoint definesgroup_byas a query parameter withtype: "string"anddefault: "time"(line 253–260), but the response schemaUrlStatisticsV1Responsedefinesgroup_byas an array of strings (lines 1272–1277). This inconsistency may confuse API consumers.Clarify the contract: does the client pass a comma-separated string that the server parses into an array, or should the parameter definition reflect an array-serialization strategy (e.g.,
style: "form"withexplode: false)?If
group_byis meant to be a comma-separated string at the query level but an array in the response, add clarity:{ "name": "group_by", "in": "query", "required": false, "description": "Comma-separated dimensions: time, browser, os, country, city, referrer, short_code. Server parses this into an array for the response.", "schema": { "type": "string", "default": "time" } }Alternatively, use OpenAPI array serialization if multiple query parameters are intended:
{ "name": "group_by", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": {"type": "string"}, "default": ["time"] } }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
openapi-v1.json(1 hunks)
🧰 Additional context used
🪛 Checkov (3.2.334)
openapi-v1.json
[medium] 1272-1276: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Sourcery review
🔇 Additional comments (1)
openapi-v1.json (1)
1-30: Specification structure and metadata are well-formed.The OpenAPI 3.0.3 specification includes comprehensive metadata (title, description, contact, license), proper server configuration, dual security schemes (JWT and API key), and logical operation grouping via tags. The v1 API emphasis aligns with PR objectives.
…entation for v0 API endpoints
1 participant
This pull request introduces major improvements to the Spoo.me API documentation, focusing on clarity, structure, and support for the new v1 API. The changes include reorganizing the documentation to distinguish between v1 and legacy v0 APIs, adding comprehensive guidance on API key authentication, updating code examples to use the new endpoints and request formats, and enhancing feature descriptions throughout the docs.
Documentation Structure and API Versioning
docs.json. API v1 endpoints and features are now grouped distinctly, making it easier for users to find relevant information. [1] [2] [3]API Key Authentication and Management
api-keys.mdxpage provides a detailed guide on creating, managing, and using API keys for programmatic access to Spoo.me, including scopes, rate limits, security best practices, and troubleshooting.Code Examples and Endpoint Updates
Feature and Community Updates
Other Improvements
.nvmrcfile is updated to specify Node.js version 24 for development consistency.These updates make the documentation clearer, easier to navigate, and fully aligned with the latest Spoo.me API capabilities.
Summary by Sourcery
Overhaul the Spoo.me documentation to fully support and promote the new v1 API while retaining legacy v0 content.
Enhancements:
Documentation:
Summary by CodeRabbit
New Features
Documentation