docs: add management api sdk page #7375
Conversation
Dangerous URL checkNo absolute URLs to prisma.io/docs found. |
WalkthroughTwo documentation updates to Postgres Management API: added a TypeScript SDK recommendation tip to the existing Management API overview, and created a new comprehensive guide covering SDK installation, OAuth 2.0 authentication flow with PKCE, API surface, token management, and environment-specific usage examples. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Possibly related PRs
Pre-merge checks✅ Passed checks (3 passed)
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. Comment |
Redirect checkThis PR probably requires the following redirects to be added to static/_redirects:
|
Deploying docs with
|
| Latest commit: |
9fcb530
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://7a7db482.docs-51g.pages.dev |
| Branch Preview URL: | https://management-api-sdk.docs-51g.pages.dev |
![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 (1)
content/250-postgres/100-introduction/235-management-api-sdk.mdx (1)
47-128: Well-explained OAuth 2.0 PKCE flow with proper security practices.The walkthrough clearly separates the four steps and shows proper handling of state/verifier storage and cleanup. Error handling with
AuthErroris explicit, and the code examples correctly demonstrate the API client usage pattern.Minor suggestion: Consider a brief note near line 57 explaining that
offline_accessscope enables automatic token refresh (documented later at line 366), as developers reading just the auth flow section may not understand why it's being included.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
content/250-postgres/100-introduction/230-management-api.mdx(1 hunks)content/250-postgres/100-introduction/235-management-api-sdk.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
content/250-postgres/100-introduction/235-management-api-sdk.mdx
[grammar] ~124-~124: Ensure spelling is correct
Context: ... { name: 'My Project' }, }) ### 4. Logout typescript await api.logout() // Clears stored tokens ``` ## API reference ### `createManagementAPI(...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
⏰ 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). (2)
- GitHub Check: Check internal links
- GitHub Check: Cloudflare Pages
🔇 Additional comments (10)
content/250-postgres/100-introduction/235-management-api-sdk.mdx (9)
1-9: LGTM—clean frontmatter and concise overview.Frontmatter is properly formatted and metadata is SEO-friendly. The overview clearly establishes what the SDK provides and links back to the main Management API reference.
11-15: Clear and concise installation instruction.Package name is correct and the command is straightforward. Users will know exactly what to run.
17-45: Solid quick start—practical and directly applicable.The example clearly demonstrates TokenStorage interface implementation and API client initialization. Using localStorage here makes sense for a browser-focused quick start. The pattern is consistent with the detailed API reference sections that follow.
130-187: Comprehensive and clearly structured API reference.Both factory functions are well-documented with appropriate examples. The distinction between
createManagementAPI(auth-aware) andcreateManagementAPIClient(manual auth) is crystal clear. Configuration options are presented both as a table and as a TypeScript type, which aids both quick scanning and copy-paste configuration.
189-211: Clear and well-documented interface contracts.The TokenStorage interface and Tokens type are properly defined with helpful comments explaining when fields are present (e.g.,
refreshTokenonly withoffline_accessscope). The async method signatures are correct and the purpose of each method is explicit.
213-302: Excellent environment-specific examples—production-ready patterns.The three examples (VS Code, Node.js CLI, stateless web server) are thoughtfully chosen and demonstrate security best practices for each context: platform secrets API, file-based storage, and httpOnly cookies. Code is clear and readily adaptable for other similar environments. The error handling patterns shown (
catchblocks, cleanup operations) are appropriate for each use case.
304-314: Helpful type export documentation.Clearly shows how to import and use TypeScript types derived from the OpenAPI spec. This is valuable for developers who need to work with response types beyond what's auto-completed by the client methods.
316-362: Clear error handling documentation with practical examples.Both
AuthErrorandFetchErrorare well-documented with specific scenarios (OAuth callback errors, token refresh failures, network issues). The examples show practical error checking patterns and remediation paths, such as redirecting to re-login whenrefreshTokenInvalidis true. Thecauseproperty for debugging is a nice touch.
364-371: Complete token refresh explanation—rounds out the auth story.The automatic refresh behavior is clearly explained: 401 triggers refresh, concurrent requests queue, invalid refresh tokens trigger cleanup and
AuthError. The note about requiringoffline_accessscope for refresh token availability ties back nicely to earlier documentation. This section provides necessary context for production use.content/250-postgres/100-introduction/230-management-api.mdx (1)
11-13: Excellent addition—clearly guides TypeScript users to the SDK.The tip is well-positioned and accurately describes the SDK's value proposition (typed client, built-in OAuth, automatic token refresh). The link target file exists and path mapping is correct.
🍈 Lychee Link Check Report
📊 Results Overview
Errors per inputErrors in 200-orm/500-reference/250-error-reference.mdx
|
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.