---
title: API Components
description: Components for documenting REST, GraphQL, WebSocket, and gRPC APIs.
icon: api
---

# 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:

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

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

Methods are color-coded:
- `GET` — Blue
- `POST` — Green  
- `PUT` — Orange
- `PATCH` — Yellow
- `DELETE` — Red

## ParamField

Document request parameters:

```mdx
<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>
```

<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>

### 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:

```mdx
<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>
```

<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>

## Expandable (Nested Objects)

Document nested structures:

```mdx
<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>
```

<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>

## RequestExample

Show example requests:

```mdx
<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"}'
```
</RequestExample>
```

## ResponseExample

Show example responses:

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

## Complete API Page Example

```mdx
---
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:

```mdx
<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:

```mdx
<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:

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

### GraphQLQuery / GraphQLMutation

Document operations:

```mdx
<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:

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

### RpcMethod

Document RPC methods:

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

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