mirror of
https://github.com/ksyasuda/dotfiles.git
synced 2026-03-21 18:11:27 -07:00
update skills
This commit is contained in:
@@ -0,0 +1,240 @@
|
||||
## API Reference
|
||||
|
||||
**Note on Smart Shield:** Argo Smart Routing is being integrated into Cloudflare's Smart Shield product. API endpoints remain stable; existing integrations continue to work without changes.
|
||||
|
||||
### Base Endpoint
|
||||
```
|
||||
https://api.cloudflare.com/client/v4
|
||||
```
|
||||
|
||||
### Authentication
|
||||
Use API tokens with Zone:Argo Smart Routing:Edit permissions:
|
||||
|
||||
```bash
|
||||
# Headers required
|
||||
X-Auth-Email: user@example.com
|
||||
Authorization: Bearer YOUR_API_TOKEN
|
||||
```
|
||||
|
||||
### Get Argo Smart Routing Status
|
||||
|
||||
**Endpoint:** `GET /zones/{zone_id}/argo/smart_routing`
|
||||
|
||||
**Description:** Retrieves current Argo Smart Routing enablement status.
|
||||
|
||||
**cURL Example:**
|
||||
```bash
|
||||
curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing" \
|
||||
-H "Authorization: Bearer YOUR_API_TOKEN" \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"result": {
|
||||
"id": "smart_routing",
|
||||
"value": "on",
|
||||
"editable": true,
|
||||
"modified_on": "2024-01-11T12:00:00Z"
|
||||
},
|
||||
"success": true,
|
||||
"errors": [],
|
||||
"messages": []
|
||||
}
|
||||
```
|
||||
|
||||
**TypeScript SDK Example:**
|
||||
```typescript
|
||||
import Cloudflare from 'cloudflare';
|
||||
|
||||
const client = new Cloudflare({
|
||||
apiToken: process.env.CLOUDFLARE_API_TOKEN
|
||||
});
|
||||
|
||||
const status = await client.argo.smartRouting.get({ zone_id: 'your-zone-id' });
|
||||
console.log(`Argo status: ${status.value}, editable: ${status.editable}`);
|
||||
```
|
||||
|
||||
**Python SDK Example:**
|
||||
```python
|
||||
from cloudflare import Cloudflare
|
||||
|
||||
client = Cloudflare(api_token=os.environ.get('CLOUDFLARE_API_TOKEN'))
|
||||
|
||||
status = client.argo.smart_routing.get(zone_id='your-zone-id')
|
||||
print(f"Argo status: {status.value}, editable: {status.editable}")
|
||||
```
|
||||
|
||||
### Update Argo Smart Routing Status
|
||||
|
||||
**Endpoint:** `PATCH /zones/{zone_id}/argo/smart_routing`
|
||||
|
||||
**Description:** Enable or disable Argo Smart Routing for a zone.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"value": "on" // or "off"
|
||||
}
|
||||
```
|
||||
|
||||
**cURL Example:**
|
||||
```bash
|
||||
curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing" \
|
||||
-H "Authorization: Bearer YOUR_API_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"value": "on"}'
|
||||
```
|
||||
|
||||
**TypeScript SDK Example:**
|
||||
```typescript
|
||||
const result = await client.argo.smartRouting.edit({
|
||||
zone_id: 'your-zone-id',
|
||||
value: 'on',
|
||||
});
|
||||
console.log(`Updated: ${result.value} at ${result.modified_on}`);
|
||||
```
|
||||
|
||||
**Python SDK Example:**
|
||||
```python
|
||||
result = client.argo.smart_routing.edit(
|
||||
zone_id='your-zone-id',
|
||||
value='on'
|
||||
)
|
||||
print(f"Updated: {result.value} at {result.modified_on}")
|
||||
```
|
||||
|
||||
## Checking Editability Before Updates
|
||||
|
||||
**Critical:** Always check the `editable` field before attempting to enable/disable Argo. When `editable: false`, the zone has restrictions (billing not configured, insufficient permissions, or plan limitations).
|
||||
|
||||
**Pattern:**
|
||||
```typescript
|
||||
async function safelyEnableArgo(client: Cloudflare, zoneId: string): Promise<boolean> {
|
||||
const status = await client.argo.smartRouting.get({ zone_id: zoneId });
|
||||
|
||||
if (!status.editable) {
|
||||
console.error('Cannot modify Argo: editable=false (check billing/permissions)');
|
||||
return false;
|
||||
}
|
||||
|
||||
if (status.value === 'on') {
|
||||
console.log('Argo already enabled');
|
||||
return true;
|
||||
}
|
||||
|
||||
await client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' });
|
||||
console.log('Argo enabled successfully');
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
**Python Pattern:**
|
||||
```python
|
||||
def safely_enable_argo(client: Cloudflare, zone_id: str) -> bool:
|
||||
status = client.argo.smart_routing.get(zone_id=zone_id)
|
||||
|
||||
if not status.editable:
|
||||
print('Cannot modify Argo: editable=false (check billing/permissions)')
|
||||
return False
|
||||
|
||||
if status.value == 'on':
|
||||
print('Argo already enabled')
|
||||
return True
|
||||
|
||||
client.argo.smart_routing.edit(zone_id=zone_id, value='on')
|
||||
print('Argo enabled successfully')
|
||||
return True
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The TypeScript SDK provides typed error classes for robust error handling:
|
||||
|
||||
```typescript
|
||||
import Cloudflare from 'cloudflare';
|
||||
import { APIError, APIConnectionError, RateLimitError } from 'cloudflare';
|
||||
|
||||
async function enableArgoWithErrorHandling(client: Cloudflare, zoneId: string) {
|
||||
try {
|
||||
const result = await client.argo.smartRouting.edit({
|
||||
zone_id: zoneId,
|
||||
value: 'on',
|
||||
});
|
||||
return result;
|
||||
} catch (error) {
|
||||
if (error instanceof RateLimitError) {
|
||||
console.error('Rate limited. Retry after:', error.response?.headers.get('retry-after'));
|
||||
// Implement exponential backoff
|
||||
} else if (error instanceof APIError) {
|
||||
console.error('API error:', error.status, error.message);
|
||||
if (error.status === 403) {
|
||||
console.error('Permission denied - check API token scopes');
|
||||
} else if (error.status === 400) {
|
||||
console.error('Bad request - verify zone_id and payload');
|
||||
}
|
||||
} else if (error instanceof APIConnectionError) {
|
||||
console.error('Connection failed:', error.message);
|
||||
// Retry with exponential backoff
|
||||
} else {
|
||||
console.error('Unexpected error:', error);
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Python Error Handling:**
|
||||
```python
|
||||
from cloudflare import Cloudflare, APIError, RateLimitError
|
||||
|
||||
def enable_argo_with_error_handling(client: Cloudflare, zone_id: str):
|
||||
try:
|
||||
result = client.argo.smart_routing.edit(zone_id=zone_id, value='on')
|
||||
return result
|
||||
except RateLimitError as e:
|
||||
print(f"Rate limited. Retry after: {e.response.headers.get('retry-after')}")
|
||||
raise
|
||||
except APIError as e:
|
||||
print(f"API error: {e.status} - {e.message}")
|
||||
if e.status == 403:
|
||||
print('Permission denied - check API token scopes')
|
||||
elif e.status == 400:
|
||||
print('Bad request - verify zone_id and payload')
|
||||
raise
|
||||
except Exception as e:
|
||||
print(f"Unexpected error: {e}")
|
||||
raise
|
||||
```
|
||||
|
||||
## Response Schema
|
||||
|
||||
All Argo Smart Routing API responses follow this structure:
|
||||
|
||||
```typescript
|
||||
interface ArgoSmartRoutingResponse {
|
||||
result: {
|
||||
id: 'smart_routing';
|
||||
value: 'on' | 'off';
|
||||
editable: boolean;
|
||||
modified_on: string; // ISO 8601 timestamp
|
||||
};
|
||||
success: boolean;
|
||||
errors: Array<{
|
||||
code: number;
|
||||
message: string;
|
||||
}>;
|
||||
messages: Array<string>;
|
||||
}
|
||||
```
|
||||
|
||||
## Key Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `value` | `"on" \| "off"` | Current enablement status |
|
||||
| `editable` | `boolean` | Whether changes are allowed (check before PATCH) |
|
||||
| `modified_on` | `string` | ISO timestamp of last modification |
|
||||
| `success` | `boolean` | Whether request succeeded |
|
||||
| `errors` | `Array` | Error details if `success: false`
|
||||
Reference in New Issue
Block a user