API Components

Syntext provides specialized components for documenting APIs across multiple protocols: REST, GraphQL, WebSocket, gRPC, and event-driven systems.

Endpoint

Display API endpoint information:

<Endpoint method="POST" path="/v1/users" />

Methods are color-coded:

• GET — Blue
• POST — Green
• PUT — Orange
• PATCH — Yellow
• DELETE — Red

ParamField

Document request parameters:

<ParamField name="email" type="string" required>
User's email address. Must be unique across the organization.
</ParamField>

<ParamField name="role" type="string" default="member">
User role. One of: `admin`, `editor`, `member`.
</ParamField>

<ParamField name="metadata" type="object">
Optional key-value pairs for custom data.
</ParamField>

User's email address. Must be unique across the organization.

User role. One of: admin, editor, member.

Optional key-value pairs for custom data.

ParamField Props

Prop	Type	Description
name	string	Parameter name (required)
type	string	Data type (required)
required	boolean	Mark as required
default	string	Default value
children	ReactNode	Description

ResponseField

Document response fields:

<ResponseField name="id" type="string">
Unique identifier for the user.
</ResponseField>

<ResponseField name="created_at" type="string" format="ISO 8601">
Timestamp when the user was created.
</ResponseField>

Unique identifier for the user.

Timestamp when the user was created.

Expandable (Nested Objects)

Document nested structures:

<Expandable title="address" type="object">
<ResponseField name="street" type="string">
Street address
</ResponseField>
<ResponseField name="city" type="string">
City name
</ResponseField>
<ResponseField name="country" type="string">
ISO country code
</ResponseField>
</Expandable>

Street address

City name

ISO country code

RequestExample

Show example requests:

<RequestExample>
```bash title="cURL"
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "alice@example.com", "name": "Alice"}'

```

ResponseExample

Show example responses:

<ResponseExample>
```json title="200 OK"
{
"id": "usr_abc123",
"email": "alice@example.com",
"name": "Alice",
"created_at": "2024-01-15T12:00:00Z"
}

```

Complete API Page Example

---
title: Create User
protocol: rest
method: POST
endpoint: /v1/users
---

# Create User

Create a new user account.

<Endpoint method="POST" path="/v1/users" />

## Request Body

<ParamField name="email" type="string" required>
User's email address.
</ParamField>

<ParamField name="name" type="string" required>
User's display name.
</ParamField>

<ParamField name="role" type="string" default="member">
User role: `admin`, `editor`, or `member`.
</ParamField>

## Response

<ResponseField name="id" type="string">
Unique user identifier.
</ResponseField>

<ResponseField name="email" type="string">
User's email address.
</ResponseField>

## Examples

<CodeGroup>
\`\`\`bash title="cURL"
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer $API_KEY" \
-d '{"email": "alice@example.com", "name": "Alice"}'
\`\`\`

\`\`\`typescript title="TypeScript"
const user = await client.users.create({
email: "alice@example.com",
name: "Alice"
});
\`\`\`
</CodeGroup>

WebSocket Components

WsEvent

Document WebSocket events:

<WsEvent name="order.created" direction="server">
Fired when a new order is placed.
</WsEvent>

<WsEvent name="subscribe" direction="client">
Subscribe to a channel.
</WsEvent>

ConnectionFlow

Visual connection lifecycle:

<ConnectionFlow>
1. Client connects to `wss://api.example.com/ws`
2. Server sends `connected` event with session ID
3. Client sends `authenticate` with API key
4. Server confirms with `authenticated` event
</ConnectionFlow>

GraphQL Components

GraphQLType

Document GraphQL types:

<GraphQLType name="User">
Represents a user account in the system.
</GraphQLType>

GraphQLQuery / GraphQLMutation

Document operations:

<GraphQLQuery name="user" returns="User">
Fetch a user by ID.
</GraphQLQuery>

<GraphQLMutation name="createUser" returns="User">
Create a new user account.
</GraphQLMutation>

gRPC Components

GrpcService

Document gRPC services:

<GrpcService name="UserService">
User management operations.
</GrpcService>

RpcMethod

Document RPC methods:

<RpcMethod name="CreateUser" type="unary">
Create a new user.
</RpcMethod>

<RpcMethod name="StreamUsers" type="server-stream">
Stream all users matching criteria.
</RpcMethod>