Skip to content

Align English API docs with actual CLI commands #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Align English API docs with actual CLI commands #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 55 additions & 1 deletion en/architecture/tech-stack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,61 @@ Exit with Code

---

## Design Principles
## Yida API calls

### Base configuration

```javascript
const BASE_URL = 'https://www.aliwork.com';

// Request headers
const headers = {
'Content-Type': 'application/json',
'X-Csrf-Token': csrfToken,
'Cookie': cookies,
};
```

### Core APIs

| Endpoint | Purpose |
|----------|---------|
| `/dingtalk/web/APP_xxx/xxx` | App internal API |
| `/dingtalk/web/APP_xxx/v1/form/searchFormDatas.json` | Form data query |
| `/dingtalk/web/APP_xxx/v1/form/saveFormData.json` | Save form data |
| `/dingtalk/web/APP_xxx/v1/form/getFormDataById.json` | Get form data by ID |
| `/dingtalk/web/APP_xxx/v1/form/updateFormData.json` | Update form data |
| `/dingtalk/web/APP_xxx/v1/process/getInstances.json` | Process instance query |
| `/dingtalk/web/APP_xxx/v1/process/getInstanceById.json` | Get process instance by ID |
| `/dingtalk/web/APP_xxx/v1/process/startInstance.json` | Start process instance |
| `/dingtalk/web/APP_xxx/v1/task/executeTask.json` | Execute task |
| `/dingtalk/web/APP_xxx/v1/task/getTasks.json` | List tasks |
| `/query/newconnector/listConnector.json` | List connectors |
| `/query/newconnector/createOrUpdateConnector.json` | Create or update connector |
| `/query/newconnector/getConnectorDetail.json` | Get connector detail |
| `/query/newconnector/testConnector.json` | Test connector action |

---

## Security design

1. **Cookie encrypted storage** - Local cache is stored encrypted
2. **CSRF token verification** - Every request includes a token
3. **No hardcoded credentials** - All credentials are dynamically obtained
4. **Environment isolation** - Independent across different AI tool environments

---

## Performance optimization

1. **Lazy-load translation files** - Language packs loaded on demand
2. **Local schema caching** - Reduces API calls
3. **Concurrent request control** - Prevents rate limiting from excessive requests
4. **Incremental updates** - Form updates use merge instead of overwrite

---

## Design principles

### 1. Single Responsibility

Expand Down
182 changes: 114 additions & 68 deletions en/features/connector.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: "Connectors (HTTP Integration)"
title: "Connectors (HTTP integration)"
description: "Integrate Yida applications with external APIs through HTTP connectors."
icon: "plug"
---
Expand All @@ -8,26 +8,26 @@ OpenYida provides powerful HTTP connector management, supporting intelligent con

---

## Feature Overview
## Feature overview

<CardGroup cols={2}>
<Card title="Smart Creation" icon="wand-magic-sparkles">
<Card title="Smart creation" icon="wand-magic-sparkles">
Automatically parse and create connectors from curl commands, with auth extraction.
</Card>
<Card title="API Management" icon="code">
<Card title="API management" icon="code">
Full connector lifecycle: create, update, test, delete.
</Card>
<Card title="Auth Support" icon="key">
<Card title="Auth support" icon="key">
Supports Bearer Token, API Key, OAuth2, and more.
</Card>
<Card title="Action Management" icon="play">
<Card title="Action management" icon="play">
Add, test, and manage connector execution actions.
</Card>
</CardGroup>

---

## Smart Connector Creation
## Smart connector creation

Create connectors from curl commands with one click:

Expand All @@ -40,88 +40,124 @@ openyida connector smart-create \

Smart creation process:

1. **Parse API Info** - Extract protocol, host, method, path, auth type
2. **Match Existing** - Find existing connectors with same host and auth
3. **Generate Config** - Auto-build OpenAPI format connector definition
4. **Create or Update** - Create new connector or add actions to existing
1. **Parse API info** - Extract protocol, host, method, path, auth type
2. **Match existing** - Find existing connectors with same host and auth
3. **Generate config** - Auto-build OpenAPI format connector definition
4. **Create or update** - Create new connector or add actions to existing

---

## Connector Management Commands
## Connector management commands

### List Connectors
### List connectors

```bash
# List all connectors
openyida connector list

# List with pagination
openyida connector list --page 1 --size 20

# Filter by app
openyida connector list --app <appId>
```

### Get Connector Details
### Create connector

```bash
openyida connector get --id <connectorId>
openyida connector create "Connector Name" "api.example.com" \
--operations ./operations.json \
--protocol https \
--desc "Connector description"
```

### Update Connector
<Note>
The `method` field in the operations JSON file is automatically normalized to lowercase (e.g., `"POST"` becomes `"post"`). If `method` is not specified, it defaults to `"get"`.
</Note>

### Get connector details

```bash
openyida connector update \
--id <connectorId> \
--name "New Name" \
--desc "Updated description"
openyida connector detail <connector-id>
```

### Delete Connector
### Delete connector

```bash
openyida connector delete --id <connectorId> [--force]
openyida connector delete <connector-id> --force
```

---

## Action Management
## Action management

### Add Action
### Add execution action

```bash
openyida connector action add \
--connector <connectorId> \
--name "Get Users" \
--method GET \
--path "/v1/users" \
--params '[{"name":"page","type":"number"}]'
openyida connector add-action \
--connector-id <id> \
--operations ./new-action.json \
--confirm
```

<Note>
The `method` field is automatically normalized to lowercase (e.g., `"POST"` becomes `"post"`). You can specify the method in any case. If omitted, it defaults to `"get"`.
The `method` field in the operations config is automatically normalized to lowercase (e.g., `"POST"` becomes `"post"`). You can specify the method in any case. If omitted, it defaults to `"get"`.
</Note>

### Test Action
### List existing actions

```bash
openyida connector action test \
--connector <connectorId> \
openyida connector list-actions <connector-id>
```

### Test action

```bash
openyida connector test \
--connector-id <id> \
--action <actionId> \
--data '{"page": 1}'
--body '{"key": "value"}'
```

### Delete action

```bash
openyida connector delete-action <connector-id> <operation-id> --force
```

---

## Auth account management

### List auth accounts

```bash
openyida connector list-connections <connector-id>
```

### List Actions
### Create auth account

```bash
openyida connector action list --connector <connectorId>
openyida connector create-connection <connector-id> "Production Account" \
--token "Bearer xxx" \
--type bearer
```

---

## Authentication Types
## Helper tools

### Parse API info

```bash
openyida connector parse-api --curl "curl command" --output ./api-info.json
```

### Generate API doc template

| Type | Description | Use Case |
```bash
openyida connector gen-template ./my-api-template.json
```

---

## Authentication types

| Type | Description | Use case |
|------|-------------|----------|
| **None** | No authentication | Public APIs |
| **Bearer Token** | Token in Authorization header | JWT-based APIs |
Expand All @@ -131,42 +167,52 @@ openyida connector action list --connector <connectorId>

---

## Common Use Cases
## Best practices

### REST API Integration
### 1. Use environment variables for sensitive info

```bash
# Create connector for REST API
openyida connector smart-create \
--curl "curl https://api.example.com/items -H 'Authorization: Bearer token'" \
--name "Item Service"
export API_TOKEN="your-secret-token"
openyida connector smart-create --curl "curl -H 'Authorization: Bearer $API_TOKEN' ..."
```

### Webhook Handler
### 2. Create complex connectors in stages

```bash
# Create webhook connector
openyida connector create \
--name "Webhook Handler" \
--type webhook \
--url "https://hooks.example.com/webhook"
# Step 1: Create base connector
openyida connector create "DingTalk API" "oapi.dingtalk.com"

# Step 2: Add actions one by one
openyida connector add-action --connector-id <id> --operations ./action1.json
openyida connector add-action --connector-id <id> --operations ./action2.json
```

### Database Proxy
### 3. Test before enabling

```bash
# Create database connector via HTTP proxy
openyida connector smart-create \
--curl "curl -X POST https://db-proxy.example.com/query" \
--name "Database Proxy"
# Create without confirming
openyida connector add-action --connector-id <id> --operations ./action.json

# Test the action
openyida connector test --connector-id <id> --action <actionId>

# Confirm in the Yida admin console
```

---

## Best Practices
## FAQ

<AccordionGroup>
<Accordion title="What if curl command parsing fails?">
Make sure the curl command is correctly formatted with a complete URL and necessary headers. If there are special characters, wrap the command in quotes.
</Accordion>

<Accordion title="How do I update an existing connector action?">
Use the `connector add-action` command. If the action ID already exists, the system prompts you to update it.
</Accordion>

1. **Reuse Connectors** - Use same connector for same host/auth combination
2. **Naming Convention** - Use descriptive names: `{Service}-{Purpose}`
3. **Documentation** - Add clear descriptions for each action
4. **Testing** - Always test connectors before production use
5. **Security** - Never commit credentials; use environment variables
<Accordion title="What auth types are supported?">
Currently supports Bearer Token, API Key, Basic Auth, and OAuth2. Auth info in curl commands is automatically detected.
</Accordion>
</AccordionGroup>
Loading