diff --git a/client/pages/docs/DocsApiReference.tsx b/client/pages/docs/DocsApiReference.tsx new file mode 100644 index 00000000..1c74f566 --- /dev/null +++ b/client/pages/docs/DocsApiReference.tsx @@ -0,0 +1,295 @@ +import { Link } from "react-router-dom"; +import { + Card, + CardContent, + CardDescription, + CardHeader, + CardTitle, +} from "@/components/ui/card"; +import { Badge } from "@/components/ui/badge"; +import { + Table, + TableBody, + TableCell, + TableHead, + TableHeader, + TableRow, + TableCaption, +} from "@/components/ui/table"; +import { Button } from "@/components/ui/button"; +import { + KeyRound, + Network, + ServerCog, + Activity, + ShieldCheck, + ArrowRight, + AlertTriangle, + Webhook, +} from "lucide-react"; + +const apiEndpoints = [ + { + method: "POST", + path: "/v1/auth/token", + description: "Exchange client credentials for an access token", + }, + { + method: "GET", + path: "/v1/projects", + description: "List projects the current identity can access", + }, + { + method: "POST", + path: "/v1/projects", + description: "Create a project with environment defaults", + }, + { + method: "GET", + path: "/v1/projects/{projectId}/metrics", + description: "Retrieve runtime metrics and usage breakdowns", + }, + { + method: "POST", + path: "/v1/webhooks/verify", + description: "Validate webhook signatures from AeThex", + }, +]; + +const webhookTopics = [ + { + event: "deployment.succeeded", + description: + "Triggered when a deployment pipeline completes successfully with promoted build artifacts.", + }, + { + event: "deployment.failed", + description: + "Sent when a pipeline fails. Includes failure stage, summary, and recommended remediation steps.", + }, + { + event: "incident.opened", + description: "Raised when monitoring detects outages or SLA breaches in production environments.", + }, + { + event: "member.invited", + description: "Notify downstream systems when a collaborator invitation is created or accepted.", + }, +]; + +const errorExamples = [ + { + code: "401", + label: "Unauthorized", + hint: "Verify the Bearer token and ensure it has not expired.", + }, + { + code: "403", + label: "Forbidden", + hint: "The identity lacks the required scope. Request the project-admin role.", + }, + { + code: "429", + label: "Too Many Requests", + hint: "Respect the rate limit headers or enable adaptive backoff via the SDK.", + }, + { + code: "503", + label: "Service Unavailable", + hint: "Retry with exponential backoff. AeThex dashboards surface ongoing maintenance windows.", + }, +]; + +export default function DocsApiReference() { + return ( +
+
+ + + API Reference + +

Integrate programmatically with the AeThex API

+

+ The REST API exposes every core capability of the AeThex platform. Authenticate with OAuth 2.1 or + personal access tokens, call idempotent endpoints, and subscribe to webhooks to react to changes in real + time. +

+
+ +
+ + + + + Authentication flow + + + +

Use the OAuth client credentials grant for service-to-service integrations:

+ 
+{`curl -X POST https://api.aethex.dev/v1/auth/token \
+  -u CLIENT_ID:CLIENT_SECRET \
+  -d "grant_type=client_credentials" \
+  -d "scope=projects:read deployments:write"`}
+
+

+ Prefer user-scoped access? Direct builders through the hosted OAuth consent screen and exchange their + authorization code using the same endpoint. +

+ + + + + + + + Request example + + + +

+ Call the Projects endpoint with your Bearer token and inspect pagination headers for large result sets. +

+ 
+{`fetch("https://api.aethex.dev/v1/projects?page=1&limit=25", {
+  headers: {
+    Authorization: "Bearer ${TOKEN}",
+    "AeThex-Environment": "production",
+  },
+}).then(async (res) => {
+  if (!res.ok) throw new Error(await res.text());
+  console.log("Projects", await res.json());
+});`}
+
+

+ Responses include X-RateLimit-Remaining + and X-Request-ID headers. Share the + request ID when contacting support for faster triage. +

+ + +
+ +
+
+ +

Core endpoints

+
+ + + + + + Method + Path + Description + + + + {apiEndpoints.map((endpoint) => ( + + + {endpoint.method} + + + {endpoint.path} + + + {endpoint.description} + + + ))} + + + Need deeper coverage? The JavaScript SDK ships with typed request builders for every endpoint. + +
+ + +
+ +
+ + + + + Webhook topics + + + + {webhookTopics.map((topic) => ( +
+

{topic.event}

+

{topic.description}

+
+ ))} +

+ Configure webhook destinations and signing secrets from the dashboard. + Verify requests with the AeThex-Signature + header to guarantee authenticity. +

+ + + + + + + + Resilience & errors + + + +

+ All endpoints are idempotent where appropriate and support conditional requests via the + If-Match header. +

+
+ {errorExamples.map((error) => ( +
+ {error.code} +
+

{error.label}

+

{error.hint}

+
+
+ ))} +
+

+ Monitor rate-limit headers and retry using an exponential backoff strategy. Persistent errors can be + escalated to the AeThex support team with the failing request ID. +

+ + +
+ +
+
+
+

Ship production-ready integrations

+

+ Combine the REST API with event webhooks for a full-duplex integration pattern. Use the official + TypeScript SDK for typed helpers or generate your own client with the published OpenAPI schema. +

+
+
+ + +
+
+
+
+ ); +}