{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "api-documentation-page", "title": "Api Documentation Page", "type": "registry:page", "files": [ { "path": "packages/registry-react/blocks/api-documentation-page/ApiDocumentationPage.tsx", "content": "'use client'\n\nimport * as React from 'react'\nimport { Check, Copy, CornerDownRight, Globe, Server, ShieldCheck, Terminal, Zap } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Badge } from '@/components/ui/badge'\nimport { Button } from '@/components/ui/button'\nimport { Card } from '@/components/ui/card'\nimport { Separator } from '@/components/ui/separator'\nimport { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table'\n\nexport interface ApiDocumentationPageProps {\n className?: string\n}\n\ntype LanguageKey = 'curl' | 'node' | 'python' | 'go' | 'ruby'\ntype StatusKey = '200' | '400' | '401'\n\ninterface HeaderItem {\n name: string\n type: string\n required: boolean\n sample: string\n description: string\n}\n\nconst headersList: HeaderItem[] = [\n {\n name: 'Authorization',\n type: 'string',\n required: true,\n sample: 'Bearer uipkge_live_51Msz...',\n description: 'Secret API key prefixed with uipkge_live_ or sk_test_. Pass in the HTTP Authorization header.',\n },\n {\n name: 'Content-Type',\n type: 'string',\n required: true,\n sample: 'application/json',\n description: 'Specifies the media type of the request body. Must be application/json.',\n },\n {\n name: 'Idempotency-Key',\n type: 'string (UUID)',\n required: false,\n sample: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',\n description: 'Unique client-generated key that prevents duplicate executions if a request is retried.',\n },\n]\n\ninterface NestedParam {\n name: string\n type: string\n required: boolean\n description: string\n example?: string\n}\n\ninterface BodyParam {\n name: string\n type: string\n required: boolean\n description: string\n example?: string\n nested?: NestedParam[]\n}\n\nconst bodyParams: BodyParam[] = [\n {\n name: 'customer_id',\n type: 'string',\n required: true,\n description: 'Unique customer identifier for the subscriber. Must begin with the prefix cus_.',\n example: '\"cus_N63vKZbI8O8yWp\"',\n },\n {\n name: 'plan_id',\n type: 'string',\n required: true,\n description: 'Identifier of the subscription tier to enroll the customer into.',\n example: '\"plan_pro_monthly\"',\n },\n {\n name: 'items',\n type: 'array of objects',\n required: true,\n description: 'List of subscription line items defining the base plan and any optional recurring addons.',\n nested: [\n {\n name: 'items[].price_id',\n type: 'string',\n required: true,\n description: 'Unique price object identifier corresponding to a catalog product.',\n example: '\"price_1Msz82eZvKYlo2C\"',\n },\n {\n name: 'items[].quantity',\n type: 'integer',\n required: false,\n description: 'Unit quantity of the specified price item. Defaults to 1 if omitted.',\n example: '1',\n },\n ],\n },\n {\n name: 'payment_method_id',\n type: 'string',\n required: false,\n description: 'Attached payment method ID (pm_...) to charge. If omitted, uses the customer default payment source.',\n example: '\"pm_1OdVq82eZvKYlo2C\"',\n },\n {\n name: 'billing_cycle_anchor',\n type: 'integer (timestamp)',\n required: false,\n description: 'Future Unix timestamp that marks the beginning of recurring billing cycles.',\n example: '1717200000',\n },\n {\n name: 'trial_period_days',\n type: 'integer',\n required: false,\n description: 'Number of zero-charge trial days before regular billing begins (1 to 90).',\n example: '14',\n },\n {\n name: 'coupon_code',\n type: 'string',\n required: false,\n description: 'Valid discount or promotional coupon applied to initial invoices.',\n example: '\"LAUNCH2026\"',\n },\n {\n name: 'metadata',\n type: 'object',\n required: false,\n description: 'Arbitrary key-value map for attribution and custom IDs. Supports up to 50 keys, max 500 chars/value.',\n example: '{\"referrer\": \"onboarding_flow\"}',\n },\n]\n\ninterface ResponseAttr {\n name: string\n type: string\n description: string\n example: string\n}\n\nconst responseAttributes: ResponseAttr[] = [\n {\n name: 'id',\n type: 'string',\n description: 'Unique identifier for the subscription entity, prefixed with sub_.',\n example: '\"sub_1Om48B2eZvKYlo2CqO8k2\"',\n },\n {\n name: 'object',\n type: 'string',\n description: 'String representing the object type. Always subscription.',\n example: '\"subscription\"',\n },\n {\n name: 'customer',\n type: 'string',\n description: 'Customer identifier associated with this subscription record.',\n example: '\"cus_N63vKZbI8O8yWp\"',\n },\n {\n name: 'status',\n type: 'string',\n description: 'Current lifecycle status: trialing, active, past_due, canceled, unpaid, or incomplete.',\n example: '\"trialing\"',\n },\n {\n name: 'current_period_start',\n type: 'integer (timestamp)',\n description: 'Unix timestamp marking the start of the current active billing cycle.',\n example: '1717200000',\n },\n {\n name: 'current_period_end',\n type: 'integer (timestamp)',\n description: 'Unix timestamp marking the end of the current cycle and scheduled renewal date.',\n example: '1719792000',\n },\n {\n name: 'trial_end',\n type: 'integer (timestamp) | null',\n description: 'Unix timestamp when the free trial period concludes and billing begins.',\n example: '1718409600',\n },\n {\n name: 'cancel_at_period_end',\n type: 'boolean',\n description: 'If true, the subscription will terminate automatically at the end of the current period.',\n example: 'false',\n },\n {\n name: 'latest_invoice',\n type: 'string',\n description: 'Identifier of the most recent invoice generated for this subscription (in_...).',\n example: '\"in_1Om48B2eZvKYlo2Cj891\"',\n },\n]\n\ninterface StatusPill {\n code: StatusKey\n label: string\n summary: string\n dotColor: string\n}\n\nconst statusPills: StatusPill[] = [\n {\n code: '200',\n label: '200 OK',\n summary: 'Subscription created successfully. Returns full subscription entity.',\n dotColor: 'bg-success',\n },\n {\n code: '400',\n label: '400 Bad Request',\n summary: 'Missing required parameters or malformed JSON payload.',\n dotColor: 'bg-warning',\n },\n {\n code: '401',\n label: '401 Unauthorized',\n summary: 'Missing, expired, or invalid Bearer secret API key.',\n dotColor: 'bg-destructive',\n },\n]\n\nconst requestSnippets: Record = {\n curl: `curl -X POST https://api.acme.com/v1/customers/subscriptions \\\\\n -H \"Authorization: Bearer uipkge_live_51Msz...\" \\\\\n -H \"Content-Type: application/json\" \\\\\n -H \"Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d\" \\\\\n -d '{\n \"customer_id\": \"cus_N63vKZbI8O8yWp\",\n \"plan_id\": \"plan_pro_monthly\",\n \"payment_method_id\": \"pm_1OdVq82eZvKYlo2C\",\n \"billing_cycle_anchor\": 1717200000,\n \"items\": [\n {\n \"price_id\": \"price_1Msz82eZvKYlo2C\",\n \"quantity\": 1\n },\n {\n \"price_id\": \"price_addon_seats_pro\",\n \"quantity\": 5\n }\n ],\n \"trial_period_days\": 14,\n \"coupon_code\": \"LAUNCH2026\",\n \"metadata\": {\n \"referrer\": \"onboarding_flow\",\n \"account_manager\": \"priya.raman\"\n }\n }'`,\n node: `import Acme from '@acme/sdk'\n\nconst acme = new Acme({\n apiKey: process.env.ACME_SECRET_KEY,\n})\n\nconst subscription = await acme.subscriptions.create({\n customerId: 'cus_N63vKZbI8O8yWp',\n planId: 'plan_pro_monthly',\n paymentMethodId: 'pm_1OdVq82eZvKYlo2C',\n billingCycleAnchor: 1717200000,\n items: [\n { priceId: 'price_1Msz82eZvKYlo2C', quantity: 1 },\n { priceId: 'price_addon_seats_pro', quantity: 5 },\n ],\n trialPeriodDays: 14,\n couponCode: 'LAUNCH2026',\n metadata: {\n referrer: 'onboarding_flow',\n accountManager: 'priya.raman',\n },\n}, {\n idempotencyKey: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',\n})\n\nconsole.log(subscription.id)`,\n python: `import os\nimport acme\n\nacme.api_key = os.environ.get(\"ACME_SECRET_KEY\")\n\nsubscription = acme.Subscription.create(\n customer_id=\"cus_N63vKZbI8O8yWp\",\n plan_id=\"plan_pro_monthly\",\n payment_method_id=\"pm_1OdVq82eZvKYlo2C\",\n billing_cycle_anchor=1717200000,\n items=[\n {\"price_id\": \"price_1Msz82eZvKYlo2C\", \"quantity\": 1},\n {\"price_id\": \"price_addon_seats_pro\", \"quantity\": 5},\n ],\n trial_period_days=14,\n coupon_code=\"LAUNCH2026\",\n metadata={\n \"referrer\": \"onboarding_flow\",\n \"account_manager\": \"priya.raman\",\n },\n idempotency_key=\"9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d\",\n)\n\nprint(subscription.id)`,\n go: `package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"os\"\n\n\t\"github.com/acme/acme-go\"\n)\n\nfunc main() {\n\tclient := acme.NewClient(os.Getenv(\"ACME_SECRET_KEY\"))\n\n\tparams := &acme.SubscriptionCreateParams{\n\t\tCustomerID: acme.String(\"cus_N63vKZbI8O8yWp\"),\n\t\tPlanID: acme.String(\"plan_pro_monthly\"),\n\t\tPaymentMethodID: acme.String(\"pm_1OdVq82eZvKYlo2C\"),\n\t\tItems: []*acme.SubscriptionItemParams{\n\t\t\t{PriceID: acme.String(\"price_1Msz82eZvKYlo2C\"), Quantity: acme.Int64(1)},\n\t\t\t{PriceID: acme.String(\"price_addon_seats_pro\"), Quantity: acme.Int64(5)},\n\t\t},\n\t\tTrialPeriodDays: acme.Int64(14),\n\t\tCouponCode: acme.String(\"LAUNCH2026\"),\n\t\tMetadata: map[string]string{\n\t\t\t\"referrer\": \"onboarding_flow\",\n\t\t\t\"account_manager\": \"priya.raman\",\n\t\t},\n\t}\n\n\tsub, err := client.Subscriptions.New(context.Background(), params)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Printf(\"Created subscription: %s\\\\n\", sub.ID)\n}`,\n ruby: `require \"acme\"\n\nAcme.api_key = ENV[\"ACME_SECRET_KEY\"]\n\nsubscription = Acme::Subscription.create(\n {\n customer_id: \"cus_N63vKZbI8O8yWp\",\n plan_id: \"plan_pro_monthly\",\n payment_method_id: \"pm_1OdVq82eZvKYlo2C\",\n billing_cycle_anchor: 1717200000,\n items: [\n { price_id: \"price_1Msz82eZvKYlo2C\", quantity: 1 },\n { price_id: \"price_addon_seats_pro\", quantity: 5 }\n ],\n trial_period_days: 14,\n coupon_code: \"LAUNCH2026\",\n metadata: {\n referrer: \"onboarding_flow\",\n account_manager: \"priya.raman\"\n }\n },\n { idempotency_key: \"9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d\" }\n)\n\nputs subscription.id`,\n}\n\nconst responseSnippets: Record = {\n '200': `{\n \"id\": \"sub_1Om48B2eZvKYlo2CqO8k2\",\n \"object\": \"subscription\",\n \"customer\": \"cus_N63vKZbI8O8yWp\",\n \"status\": \"trialing\",\n \"plan\": {\n \"id\": \"plan_pro_monthly\",\n \"name\": \"Pro Tier Monthly\",\n \"amount\": 4900,\n \"currency\": \"usd\",\n \"interval\": \"month\"\n },\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_98f12a3bc4d5\",\n \"price\": \"price_1Msz82eZvKYlo2C\",\n \"quantity\": 1\n },\n {\n \"id\": \"si_98f12a3bc4d6\",\n \"price\": \"price_addon_seats_pro\",\n \"quantity\": 5\n }\n ],\n \"total_count\": 2\n },\n \"current_period_start\": 1717200000,\n \"current_period_end\": 1719792000,\n \"trial_start\": 1717200000,\n \"trial_end\": 1718409600,\n \"cancel_at_period_end\": false,\n \"latest_invoice\": \"in_1Om48B2eZvKYlo2Cj891\",\n \"metadata\": {\n \"account_manager\": \"priya.raman\",\n \"referrer\": \"onboarding_flow\"\n },\n \"created_at\": 1717200000\n}`,\n '400': `{\n \"error\": {\n \"type\": \"invalid_request_error\",\n \"code\": \"parameter_missing\",\n \"param\": \"customer_id\",\n \"message\": \"Missing required param: customer_id. Please provide a valid customer identifier.\",\n \"doc_url\": \"https://api.acme.com/docs/errors#parameter_missing\"\n }\n}`,\n '401': `{\n \"error\": {\n \"type\": \"authentication_error\",\n \"code\": \"invalid_api_key\",\n \"message\": \"Invalid API Key provided: uipkge_live_51Msz... Check your secret key in dashboard.\",\n \"doc_url\": \"https://api.acme.com/docs/errors#authentication\"\n }\n}`,\n}\n\nexport function ApiDocumentationPage({ className }: ApiDocumentationPageProps) {\n const [selectedLang, setSelectedLang] = React.useState('curl')\n const [selectedStatus, setSelectedStatus] = React.useState('200')\n const [copiedEndpoint, setCopiedEndpoint] = React.useState(false)\n const [copiedRequest, setCopiedRequest] = React.useState(false)\n const [copiedResponse, setCopiedResponse] = React.useState(false)\n\n const endpointUrl = 'https://api.acme.com/v1/customers/subscriptions'\n const endpointPath = '/v1/customers/subscriptions'\n\n const copyEndpoint = React.useCallback(() => {\n if (typeof navigator !== 'undefined' && navigator.clipboard) {\n navigator.clipboard.writeText(endpointUrl)\n setCopiedEndpoint(true)\n setTimeout(() => {\n setCopiedEndpoint(false)\n }, 2000)\n }\n }, [endpointUrl])\n\n const copyRequestSnippet = React.useCallback(() => {\n const code = requestSnippets[selectedLang]\n if (typeof navigator !== 'undefined' && navigator.clipboard) {\n navigator.clipboard.writeText(code)\n setCopiedRequest(true)\n setTimeout(() => {\n setCopiedRequest(false)\n }, 2000)\n }\n }, [selectedLang])\n\n const copyResponseSnippet = React.useCallback(() => {\n const json = responseSnippets[selectedStatus]\n if (typeof navigator !== 'undefined' && navigator.clipboard) {\n navigator.clipboard.writeText(json)\n setCopiedResponse(true)\n setTimeout(() => {\n setCopiedResponse(false)\n }, 2000)\n }\n }, [selectedStatus])\n\n return (\n \n {/* Top Reference Navigation Bar */}\n
\n
\n
\n \n
\n
\n Acme Billing API\n /\n Subscriptions\n \n v2026-03-01\n \n
\n
\n\n
\n
\n \n Base:\n https://api.acme.com/v1\n
\n \n
\n
\n\n {/* Two-Column Reference Layout */}\n
\n {/* Left Main Column: Documentation Prose & Schema Tables (approx 58-60%) */}\n
\n {/* Endpoint Section Header */}\n
\n
\n \n POST\n \n \n {endpointPath}\n \n
\n\n
\n

Create a subscription

\n

\n Creates a new recurring subscription contract for an existing customer account. If a default payment\n method is attached, initial recurring invoices are calculated and charged upon trial conclusion or cycle\n anchor date.\n

\n
\n\n {/* Metadata Badges */}\n
\n
\n \n Idempotent:\n Yes (via Idempotency-Key)\n
\n\n
\n \n Auth:\n Bearer Secret Key\n
\n\n
\n \n Rate Limit:\n 100 req/min\n
\n
\n
\n\n \n\n {/* Request Headers */}\n
\n
\n

Request Headers

\n \n HTTP/1.1 & HTTP/2\n \n
\n\n \n
\n \n \n \n Header\n Type\n Requirement\n Description\n \n \n \n {headersList.map((header) => (\n \n {header.name}\n \n \n {header.type}\n \n \n \n {header.required ? (\n \n REQUIRED\n \n ) : (\n optional\n )}\n \n \n

{header.description}

\n \n Sample: {header.sample}\n \n \n \n ))}\n \n
\n
\n \n
\n\n {/* Request Body Parameters */}\n
\n
\n
\n

\n Request Body Parameters\n

\n

Provide arguments in a standard JSON payload format.

\n
\n \n application/json\n \n
\n\n \n
\n \n \n \n Parameter\n Type\n Requirement\n Description & Constraints\n \n \n \n {bodyParams.map((param) => (\n \n \n {param.name}\n \n \n {param.type}\n \n \n \n {param.required ? (\n \n REQUIRED\n \n ) : (\n optional\n )}\n \n \n

{param.description}

\n {param.example && (\n
\n Example: \n {param.example}\n
\n )}\n \n \n\n {/* Nested Schema Rows */}\n {param.nested?.map((child) => (\n \n \n
\n \n {child.name}\n
\n \n \n \n {child.type}\n \n \n \n {child.required ? (\n \n REQUIRED\n \n ) : (\n optional\n )}\n \n \n

{child.description}

\n {child.example && (\n
\n Example: \n {child.example}\n
\n )}\n \n \n ))}\n \n ))}\n \n
\n
\n \n
\n\n {/* Response Schema Attributes */}\n
\n
\n

\n Response Object Attributes\n

\n

\n Properties returned in the 200 OK HTTP JSON payload representation.\n

\n
\n\n \n
\n \n \n \n Attribute\n Type\n Description\n Sample Value\n \n \n \n {responseAttributes.map((attr) => (\n \n {attr.name}\n \n \n {attr.type}\n \n \n {attr.description}\n {attr.example}\n \n ))}\n \n
\n
\n \n
\n
\n\n {/* Right Column: Interactive Code & Response Inspector (approx 40-42%, Dark Slate) */}\n \n
\n \n )\n}\n", "type": "registry:page", "target": "~/components/blocks/ApiDocumentationPage.tsx" } ], "dependencies": [ "lucide-react" ], "devDependencies": [], "registryDependencies": [ "https://uipkge.dev/r/react/badge.json", "https://uipkge.dev/r/react/button.json", "https://uipkge.dev/r/react/card.json", "https://uipkge.dev/r/react/separator.json", "https://uipkge.dev/r/react/table.json" ], "description": "Stripe and Mintlify style two-pane API documentation reference page with HTTP method badge, endpoint path, headers, request parameter tables with nested schema hints, response attributes, interactive multi-language code snippets (cURL, Node.js, Python, Go, Ruby), and status response tabs with copy actions.", "categories": [ "devops", "app" ] }