Skip to content

Commit 042afc1

Browse files
riderxriderx
committed
doc: better public endpoint doc
1 parent 5c86419 commit 042afc1

File tree

9 files changed

+1513
-525
lines changed

9 files changed

+1513
-525
lines changed

‎src/content/docs/docs/public-api/api-keys.mdx‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
title: "API Keys"
3+
description: "API Keys endpoint documentation"
4+
sidebar:
5+
order: 3
6+
---
7+
8+
API keys are used to authenticate requests to the Capgo API. Each key can have different permissions (modes) to control access levels. Keys are organization-specific and should be managed carefully as they grant access to your Capgo resources.
9+
10+
## Key Modes
11+
12+
- **read**: Can only read data, no modifications allowed
13+
- **write**: Can read and modify data, but cannot upload new bundles
14+
- **upload**: Can read, modify, and upload new bundles
15+
- **all**: Full access to all operations
16+
17+
## Security Best Practices
18+
19+
1. **Principle of Least Privilege**: Always use the most restrictive mode that still allows your integration to function
20+
2. **Regular Rotation**: Rotate your API keys periodically
21+
3. **Secure Storage**: Store API keys securely and never commit them to version control
22+
4. **Monitoring**: Monitor API key usage and revoke any compromised keys immediately
23+
24+
## Endpoints
25+
26+
### GET
27+
28+
`https://api.capgo.app/apikey/`
29+
30+
Retrieve all API keys associated with your account.
31+
32+
#### Response Type
33+
34+
```typescript
35+
interface ApiKey {
36+
created_at: string | null
37+
id: number
38+
key: string
39+
mode: 'read' | 'write' | 'upload' | 'all'
40+
name: string
41+
updated_at: string | null
42+
user_id: string
43+
}
44+
```
45+
46+
#### Example Request
47+
48+
```bash
49+
curl -H "authorization: your-api-key" https://api.capgo.app/apikey/
50+
```
51+
52+
#### Example Response
53+
54+
```json
55+
{
56+
"data": [
57+
{
58+
"id": 1,
59+
"key": "ak_123...",
60+
"mode": "read",
61+
"name": "CI/CD Read Key",
62+
"created_at": "2024-01-01T00:00:00Z",
63+
"updated_at": "2024-01-01T00:00:00Z",
64+
"user_id": "user_123"
65+
},
66+
{
67+
"id": 2,
68+
"key": "ak_456...",
69+
"mode": "upload",
70+
"name": "Deploy Bot",
71+
"created_at": "2024-01-02T00:00:00Z",
72+
"updated_at": "2024-01-02T00:00:00Z",
73+
"user_id": "user_123"
74+
}
75+
]
76+
}
77+
```
78+
79+
### POST
80+
81+
`https://api.capgo.app/apikey/`
82+
83+
Create a new API key for a specific organization.
84+
85+
#### Query Parameters
86+
87+
```typescript
88+
interface ApiKeyCreate {
89+
org_id: string
90+
mode: 'read' | 'write' | 'upload' | 'all'
91+
}
92+
```
93+
94+
#### Example Request
95+
96+
```bash
97+
curl -X POST \
98+
-H "authorization: your-api-key" \
99+
-H "Content-Type: application/json" \
100+
-d '{
101+
"org_id": "org_123",
102+
"mode": "read"
103+
}' \
104+
https://api.capgo.app/apikey/
105+
```
106+
107+
#### Example Response
108+
109+
```json
110+
{
111+
"apikey": {
112+
"id": 3,
113+
"key": "ak_789...",
114+
"mode": "read",
115+
"name": "New API Key",
116+
"created_at": "2024-02-12T00:00:00Z",
117+
"user_id": "user_123"
118+
}
119+
}
120+
```
121+
122+
### DELETE
123+
124+
`https://api.capgo.app/apikey/:key/`
125+
126+
Delete an existing API key. Use this to revoke access immediately.
127+
128+
#### Parameters
129+
- `key`: The API key to delete (the UUID-like string) or the `id` of the API key
130+
131+
#### Example Request
132+
133+
```bash
134+
# Delete by key
135+
curl -X DELETE -H "authorization: your-api-key" https://api.capgo.app/apikey/ak_123.../
136+
137+
# Delete by ID
138+
curl -X DELETE -H "authorization: your-api-key" https://api.capgo.app/apikey/1/
139+
```
140+
141+
#### Success Response
142+
143+
```json
144+
{
145+
"success": true
146+
}
147+
```
148+
149+
## Common Use Cases
150+
151+
1. **CI/CD Integration**: Create read-only keys for CI pipelines to check deployment status
152+
2. **Deployment Automation**: Use upload mode keys for automated deployment scripts
153+
3. **Monitoring Tools**: Use read mode keys for external monitoring integrations
154+
4. **Admin Access**: Use all mode keys sparingly for administrative tools
155+
156+
## Error Handling
157+
158+
Common error scenarios and their responses:
159+
160+
```json
161+
// Invalid mode
162+
{
163+
"error": "Invalid mode specified. Must be one of: read, write, upload, all",
164+
"status": "KO"
165+
}
166+
167+
// Key not found
168+
{
169+
"error": "API key not found",
170+
"status": "KO"
171+
}
172+
173+
// Permission denied
174+
{
175+
"error": "Insufficient permissions to manage API keys",
176+
"status": "KO"
177+
}
178+
```

‎src/content/docs/docs/public-api/bundles.mdx‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
---
2+
title: "Bundles"
3+
description: "Bundles endpoint documentation"
4+
sidebar:
5+
order: 8
6+
---
7+
8+
Bundles are the core update packages in Capgo. Each bundle contains the web assets (HTML, CSS, JS) that make up your app's content. The Bundles API allows you to manage these update packages, including listing and deleting them.
9+
10+
## Understanding Bundles
11+
12+
A bundle represents a specific version of your app's web content and includes:
13+
- **Version**: Semantic version number of the bundle
14+
- **Checksum**: Unique hash to verify bundle integrity
15+
- **Storage Info**: Details about where and how the bundle is stored
16+
- **Native Requirements**: Minimum native app version requirements
17+
- **Metadata**: Creation time, ownership, and other tracking information
18+
19+
## Best Practices
20+
21+
1. **Version Management**: Use semantic versioning consistently
22+
2. **Storage Optimization**: Remove unused bundles periodically
23+
3. **Version Compatibility**: Set appropriate minimum native version requirements
24+
4. **Backup Strategy**: Maintain backups of critical bundle versions
25+
26+
## Endpoints
27+
28+
### GET
29+
30+
`https://api.capgo.app/bundle/`
31+
32+
Retrieve bundle information. Returns 50 bundles per page.
33+
34+
#### Query Parameters
35+
- `app_id`: Required. The ID of your app
36+
- `page`: Optional. Page number for pagination
37+
38+
#### Response Type
39+
40+
```typescript
41+
interface Bundle {
42+
app_id: string
43+
bucket_id: string | null
44+
checksum: string | null
45+
created_at: string | null
46+
deleted: boolean
47+
external_url: string | null
48+
id: number
49+
minUpdateVersion: string | null
50+
name: string
51+
native_packages: Json[] | null
52+
owner_org: string
53+
r2_path: string | null
54+
session_key: string | null
55+
storage_provider: string
56+
updated_at: string | null
57+
user_id: string | null
58+
}
59+
```
60+
61+
#### Example Request
62+
63+
```bash
64+
# Get all bundles
65+
curl -H "authorization: your-api-key" \
66+
"https://api.capgo.app/bundle/?app_id=app_123"
67+
68+
# Get next page
69+
curl -H "authorization: your-api-key" \
70+
"https://api.capgo.app/bundle/?app_id=app_123&page=1"
71+
```
72+
73+
#### Example Response
74+
75+
```json
76+
{
77+
"data": [
78+
{
79+
"id": 1,
80+
"app_id": "app_123",
81+
"name": "1.0.0",
82+
"checksum": "abc123...",
83+
"minUpdateVersion": "1.0.0",
84+
"storage_provider": "r2",
85+
"created_at": "2024-01-01T00:00:00Z",
86+
"updated_at": "2024-01-01T00:00:00Z",
87+
"deleted": false,
88+
"owner_org": "org_123",
89+
"user_id": "user_123"
90+
}
91+
]
92+
}
93+
```
94+
95+
### DELETE
96+
97+
`https://api.capgo.app/bundle/`
98+
99+
Delete one or all bundles for an app. Use with caution as this action cannot be undone.
100+
101+
#### Query Parameters
102+
103+
For deleting a specific bundle:
104+
```typescript
105+
interface BundleDelete {
106+
app_id: string
107+
version: string
108+
}
109+
```
110+
111+
For deleting all bundles:
112+
```typescript
113+
interface BundleDeleteAll {
114+
app_id: string
115+
}
116+
```
117+
118+
#### Example Requests
119+
120+
```bash
121+
# Delete specific bundle
122+
curl -X DELETE \
123+
-H "authorization: your-api-key" \
124+
-H "Content-Type: application/json" \
125+
-d '{
126+
"app_id": "app_123",
127+
"version": "1.0.0"
128+
}' \
129+
https://api.capgo.app/bundle/
130+
131+
# Delete all bundles
132+
curl -X DELETE \
133+
-H "authorization: your-api-key" \
134+
-H "Content-Type: application/json" \
135+
-d '{
136+
"app_id": "app_123"
137+
}' \
138+
https://api.capgo.app/bundle/
139+
```
140+
141+
#### Success Response
142+
143+
```json
144+
{
145+
"status": "ok"
146+
}
147+
```
148+
149+
## Error Handling
150+
151+
Common error scenarios and their responses:
152+
153+
```json
154+
// Bundle not found
155+
{
156+
"error": "Bundle not found",
157+
"status": "KO"
158+
}
159+
160+
// Invalid version format
161+
{
162+
"error": "Invalid version format",
163+
"status": "KO"
164+
}
165+
166+
// Storage error
167+
{
168+
"error": "Failed to delete bundle from storage",
169+
"status": "KO"
170+
}
171+
172+
// Permission denied
173+
{
174+
"error": "Insufficient permissions to manage bundles",
175+
"status": "KO"
176+
}
177+
```
178+
179+
## Common Use Cases
180+
181+
1. **Cleanup Old Versions**
182+
```typescript
183+
// Delete outdated beta versions
184+
{
185+
"app_id": "app_123",
186+
"version": "1.0.0-beta.1"
187+
}
188+
```
189+
190+
2. **App Reset**
191+
```typescript
192+
// Remove all bundles to start fresh
193+
{
194+
"app_id": "app_123"
195+
}
196+
```
197+
198+
## Storage Considerations
199+
200+
1. **Retention Policy**: Define how long to keep old bundles
201+
2. **Size Management**: Monitor bundle sizes and storage usage
202+
3. **Backup Strategy**: Consider backing up critical versions
203+
4. **Cost Optimization**: Remove unnecessary bundles to optimize storage costs

0 commit comments

Comments
 (0)