Skip to content

Commit 850b642

Browse files
moonrailgunmoonrailgun
committed
docs: add api related documents
1 parent e375944 commit 850b642

4 files changed

Lines changed: 310 additions & 0 deletions

File tree

‎website/docs/api/_category_.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"label": "API",
3+
"position": 15,
4+
"description": "Tianji API documentation and guides"
5+
}

‎website/docs/api/authentication.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# Authentication
6+
7+
This document provides detailed instructions on how to authenticate with the Tianji API, including obtaining, using, and managing API keys.
8+
9+
## Authentication Method
10+
11+
The Tianji API uses **Bearer Token** authentication. You need to include your API key in the HTTP header of each API request.
12+
13+
### HTTP Header Format
14+
15+
```http
16+
Authorization: Bearer YOUR_API_KEY
17+
```
18+
19+
## Obtaining API Keys
20+
21+
1. Log in to your Tianji instance
22+
2. Click on your avatar in the top right corner
23+
4. Find the **API Keys** section
24+
5. Click the + button to create a new API key
25+
6. Name your API key and save it
26+
27+
## API Key Management
28+
29+
### View Existing Keys
30+
31+
In the **API Keys** section, you can see:
32+
- API key name/description
33+
- Creation date
34+
- Last used time
35+
- Usage count statistics
36+
37+
### Delete API Keys
38+
39+
If you need to revoke an API key:
40+
1. Find the API key you want to delete
41+
2. Click the **Delete** button
42+
3. Confirm the deletion operation
43+
44+
:::warning Note
45+
After deleting an API key, all applications using that key will no longer be able to access the API.
46+
:::
47+
48+
## Using API Keys
49+
50+
### cURL Example
51+
52+
```bash
53+
curl -X GET "https://your-tianji-domain.com/open/global/config" \
54+
-H "Authorization: Bearer <your_api_key_here>" \
55+
-H "Content-Type: application/json"
56+
```
57+
58+
### JavaScript/Node.js Example
59+
60+
```javascript
61+
const apiKey = '<your_api_key_here>';
62+
const baseUrl = 'https://your-tianji-domain.com/open';
63+
64+
const headers = {
65+
'Authorization': `Bearer ${apiKey}`,
66+
'Content-Type': 'application/json'
67+
};
68+
69+
// Using fetch
70+
const response = await fetch(`${baseUrl}/global/config`, {
71+
method: 'GET',
72+
headers: headers
73+
});
74+
75+
// Using axios
76+
const axios = require('axios');
77+
const response = await axios.get(`${baseUrl}/global/config`, {
78+
headers: headers
79+
});
80+
```
81+
82+
### Python Example
83+
84+
```python
85+
import requests
86+
87+
api_key = '<your_api_key_here>'
88+
base_url = 'https://your-tianji-domain.com/open'
89+
90+
headers = {
91+
'Authorization': f'Bearer {api_key}',
92+
'Content-Type': 'application/json'
93+
}
94+
95+
# Using requests library
96+
response = requests.get(f'{base_url}/global/config', headers=headers)
97+
data = response.json()
98+
```
99+
100+
### PHP Example
101+
102+
```php
103+
<?php
104+
$apiKey = '<your_api_key_here>';
105+
$baseUrl = 'https://your-tianji-domain.com/open';
106+
107+
$headers = [
108+
'Authorization: Bearer ' . $apiKey,
109+
'Content-Type: application/json'
110+
];
111+
112+
$ch = curl_init();
113+
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/global/config');
114+
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
115+
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
116+
117+
$response = curl_exec($ch);
118+
curl_close($ch);
119+
120+
$data = json_decode($response, true);
121+
?>
122+
```
123+
124+
## Permissions and Scope
125+
126+
### API Key Permissions
127+
128+
API keys inherit all permissions of their creator, including:
129+
- Access to all data in the user's workspaces
130+
- Execute all operations the user has permission for
131+
- Manage resources created by that user
132+
133+
### Workspace Access
134+
135+
API keys can only access workspaces that the user belongs to. If you need to access multiple workspaces, ensure your user account has appropriate permissions for those workspaces.
136+
137+
## Error Handling
138+
139+
### Common Authentication Errors
140+
141+
#### 401 Unauthorized
142+
143+
```json
144+
{
145+
"error": {
146+
"code": "UNAUTHORIZED",
147+
"message": "Authorization not provided"
148+
}
149+
}
150+
```
151+
152+
**Causes**:
153+
- No Authorization header provided
154+
- Incorrect API key format
155+
156+
#### 403 Forbidden
157+
158+
```json
159+
{
160+
"error": {
161+
"code": "FORBIDDEN",
162+
"message": "Insufficient access"
163+
}
164+
}
165+
```
166+
167+
**Causes**:
168+
- Invalid or deleted API key
169+
- User doesn't have permission to access the requested resource
170+
171+
### Debugging Authentication Issues
172+
173+
1. **Check API key format**: Ensure you're using the `Bearer token_here` format
174+
2. **Verify key validity**: Confirm the key still exists in the Tianji interface
175+
3. **Check permissions**: Ensure the user account has permission to access the target resource
176+
4. **Test simple endpoints**: Start by testing public endpoints like `/global/config`

‎website/docs/api/getting-started.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# API Getting Started
6+
7+
Tianji provides a complete REST API that allows you to programmatically access and operate all Tianji features. This guide will help you quickly get started with the Tianji API.
8+
9+
## Overview
10+
11+
The Tianji API is based on REST architecture and uses JSON format for data exchange. All API requests must be made over HTTPS and require proper authentication.
12+
13+
### API Base URL
14+
15+
```bash
16+
https://your-tianji-domain.com/open
17+
```
18+
19+
### Supported Features
20+
21+
Through the Tianji API, you can:
22+
23+
- Manage website analytics data
24+
- Create and manage monitoring projects
25+
- Get server status information
26+
- Manage surveys
27+
- Operate telemetry data
28+
- Create and manage workspaces
29+
30+
## Quick Start
31+
32+
### 1. Get API Key
33+
34+
Before using the API, you need to obtain an API key:
35+
36+
1. Log in to your Tianji instance
37+
2. Click on your avatar in the top right corner
38+
4. Find the **API Keys** section
39+
5. Click the + button to create a new API key
40+
6. Name your API key and save it
41+
42+
### 2. Enable OpenAPI
43+
44+
Make sure your Tianji instance has OpenAPI access enabled:
45+
46+
Set in your environment variables:
47+
```bash
48+
ALLOW_OPENAPI=true
49+
```
50+
51+
### 3. First API Call
52+
53+
Test your API connection using curl:
54+
55+
```bash
56+
curl -X GET "https://your-tianji-domain.com/open/global/config" \
57+
-H "Authorization: Bearer YOUR_API_KEY" \
58+
-H "Content-Type: application/json"
59+
```
60+
61+
## Next Steps
62+
63+
- Check the [Authentication Documentation](./authentication.md) for detailed authentication methods
64+
- Browse the [API Reference Documentation](/api) for all available endpoints
65+
- Use the [OpenAPI SDK](./openapi-sdk.md) for type-safe API calls

‎website/docs/api/openapi-sdk.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
sidebar_position: 7
3+
---
4+
5+
# OpenAPI SDK Usage Guide
6+
7+
This document provides detailed instructions on how to use the Tianji SDK to call OpenAPI interfaces and achieve complete programmatic access to Tianji services.
8+
9+
## Overview
10+
11+
The Tianji OpenAPI SDK is based on an auto-generated TypeScript client, providing type-safe API calling methods. Through the SDK, you can:
12+
13+
- Manage workspaces and websites
14+
- Retrieve analytics data and statistics
15+
- Operate monitoring projects
16+
- Manage surveys
17+
- Handle Feed channels and events
18+
- ...
19+
20+
[Complete API Documentation](/api)
21+
22+
## Installation and Initialization
23+
24+
### Install SDK
25+
26+
```bash
27+
npm install tianji-client-sdk
28+
# or
29+
yarn add tianji-client-sdk
30+
# or
31+
pnpm add tianji-client-sdk
32+
```
33+
34+
### Initialize OpenAPI Client
35+
36+
```javascript
37+
import { initOpenapiSDK } from 'tianji-client-sdk';
38+
39+
initOpenapiSDK('https://your-tianji-domain.com', {
40+
apiKey: 'your-api-key'
41+
});
42+
```
43+
44+
## Global Configuration API
45+
46+
### Get System Configuration
47+
48+
```javascript
49+
import { openApiClient } from 'tianji-client-sdk';
50+
51+
async function getSystemConfig() {
52+
try {
53+
const config = await openApiClient.GlobalService.globalConfig();
54+
55+
console.log('Allow registration:', config.allowRegister);
56+
console.log('AI features enabled:', config.enableAI);
57+
console.log('Billing enabled:', config.enableBilling);
58+
59+
return config;
60+
} catch (error) {
61+
console.error('Failed to get system configuration:', error);
62+
}
63+
}
64+
```

0 commit comments

Comments
 (0)