|
1 | | -# API Overview |
| 1 | +# API Reference Overview |
2 | 2 |
|
3 | | -Pangolin provides a rich set of APIs for catalog management, branching, merging, and authentication. |
| 3 | +Pangolin exposes a multi-tenant REST API split into three core functional areas: The Standard Iceberg REST API, the Pangolin Management API, and the Identity/Security API. |
4 | 4 |
|
5 | | -## Authentication |
| 5 | +--- |
6 | 6 |
|
7 | | -| Endpoint | Method | Description | |
8 | | -| :--- | :--- | :--- | |
9 | | -| `/api/v1/users/login` | POST | Authenticate and receive a JWT token. | |
10 | | -| `/api/v1/users/logout` | POST | Invalidate current session (optional). | |
11 | | -| `/api/v1/users/me` | GET | Get current user information. | |
12 | | -| `/api/v1/tokens` | POST | Generate a long-lived JWT token for a specific tenant/user. | |
13 | | - |
14 | | -## Iceberg REST API |
15 | | - |
16 | | -Pangolin implements the standard Apache Iceberg REST Catalog API. |
| 7 | +## 🔐 Authentication & Identity |
| 8 | +*Base Path: `/api/v1/`* |
17 | 9 |
|
18 | 10 | | Endpoint | Method | Description | |
19 | 11 | | :--- | :--- | :--- | |
20 | | -| `/v1/config` | GET | Get Iceberg client configuration. | |
21 | | -| `/v1/{tenant}/config` | GET | Get tenant-specific Iceberg client configuration. | |
22 | | -| `/v1/{prefix}/namespaces` | GET/POST | List and create namespaces. | |
23 | | -| `/v1/{prefix}/namespaces/{namespace}/tables` | GET/POST | List and create tables. | |
24 | | -| `/v1/{prefix}/namespaces/{namespace}/tables/{table}` | GET/POST/DELETE | Manage table metadata and snapshots. | |
| 12 | +| `users/login` | POST | Authenticate and receive a JWT session. | |
| 13 | +| `tokens` | POST | Generate a long-lived JWT token for a specific user. | |
| 14 | +| `auth/revoke` | POST | Invalidate current user token. | |
| 15 | +| `service-users` | GET/POST | Manage programmatic API identities. | |
| 16 | +| `service-users/{id}/rotate` | POST | Rotate API key for a service user. | |
25 | 17 |
|
26 | | -**Note**: Branching is supported via the `table@branch` syntax (e.g., `GET .../tables/my_table@dev`). |
| 18 | +--- |
27 | 19 |
|
28 | | -## Pangolin Extended APIs |
| 20 | +## 📋 Standard Iceberg API (REST Catalog) |
| 21 | +*Base Path: `/v1/`* |
29 | 22 |
|
30 | | -### Branch Operations |
| 23 | +Pangolin is 100% compliant with the [Apache Iceberg REST Specification](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml). |
31 | 24 |
|
32 | 25 | | Endpoint | Method | Description | |
33 | 26 | | :--- | :--- | :--- | |
34 | | -| `/api/v1/branches` | GET/POST | List all branches or create a new branch. | |
35 | | -| `/api/v1/branches/merge` | POST | Initiate a merge from a source branch to a target branch. | |
36 | | -| `/api/v1/branches/{name}/commits` | GET | List commit history for a specific branch. | |
37 | | - |
38 | | -### Tag Management |
39 | | - |
40 | | -| Endpoint | Method | Description | |
41 | | -| :--- | :--- | :--- | |
42 | | -| `/api/v1/tags` | GET/POST | List all tags or create a new tag. | |
43 | | -| `/api/v1/tags/{name}` | GET/DELETE | View or delete a specific tag. | |
44 | | - |
45 | | -### Merge Operations (Conflict Resolution) |
46 | | - |
47 | | -| Endpoint | Method | Description | |
48 | | -| :--- | :--- | :--- | |
49 | | -| `/api/v1/catalogs/{catalog}/merge-operations` | GET | List merge operations for a catalog. | |
50 | | -| `/api/v1/merge-operations/{id}` | GET | Get merge operation details and status. | |
51 | | -| `/api/v1/merge-operations/{id}/conflicts` | GET | List conflicts for a merge operation. | |
52 | | -| `/api/v1/conflicts/{id}/resolve` | POST | Resolve a specific conflict with a strategy. | |
53 | | -| `/api/v1/merge-operations/{id}/complete` | POST | Complete a merge after resolving all conflicts. | |
54 | | -| `/api/v1/merge-operations/{id}/abort` | POST | Abort a pending merge operation. | |
55 | | - |
56 | | -### Management CRUD |
57 | | - |
58 | | -| Entity | Endpoints | Methods | |
59 | | -| :--- | :--- | :--- | |
60 | | -| **Tenants** | `/api/v1/tenants` | GET, POST, PUT, DELETE | |
61 | | -| **Warehouses** | `/api/v1/warehouses` | GET, POST, PUT, DELETE | |
62 | | -| **Catalogs** | `/api/v1/catalogs` | GET, POST, PUT, DELETE | |
63 | | -| **Federated Catalogs** | `/api/v1/federated-catalogs` | GET, POST, DELETE, TEST | |
64 | | -| **Users** | `/api/v1/users` | GET, POST, PUT, DELETE | |
65 | | -| **Service Users**| `/api/v1/service-users` | GET, POST, PUT, DELETE, ROTATE | |
66 | | -| **Roles** | `/api/v1/roles` | GET, POST, PUT, DELETE | |
67 | | -| **Permissions** | `/api/v1/permissions` | GET, POST, DELETE | |
| 27 | +| `config` | GET | Get client configuration. | |
| 28 | +| `{prefix}/namespaces` | GET/POST | Manage catalog namespaces. | |
| 29 | +| `{prefix}/namespaces/{ns}/tables` | GET/POST | Manage tables (Standard Iceberg). | |
| 30 | +| `{prefix}/namespaces/{ns}/tables/{table}` | GET/POST | Table metadata and schema evolution. | |
68 | 31 |
|
69 | | -### Token Management |
| 32 | +> [!TIP] |
| 33 | +> **Branching**: Use the `@` suffix in the table name (e.g., `my_table@dev`) to redirect Iceberg operations to a specific Pangolin branch. |
70 | 34 |
|
71 | | -| Endpoint | Method | Description | |
72 | | -| :--- | :--- | :--- | |
73 | | -| `/api/v1/tokens` | POST | Generate a long-lived JWT token for scripts/automation. | |
74 | | -| `/api/v1/auth/revoke` | POST | Revoke current user's token. | |
75 | | -| `/api/v1/auth/revoke/{token_id}` | POST | Revoke a specific token (admin only). | |
76 | | -| `/api/v1/auth/cleanup-tokens` | POST | Clean up expired tokens (admin only). | |
77 | | -| `/api/v1/users/{user_id}/tokens` | GET | List all tokens for a specific user (admin only). | |
78 | | -| `/api/v1/tokens/{token_id}` | DELETE | Delete a specific token by ID (admin only). | |
| 35 | +--- |
79 | 36 |
|
80 | | -### System Configuration |
| 37 | +## 🏗️ Management & Data Governance |
| 38 | +*Base Path: `/api/v1/`* |
81 | 39 |
|
82 | | -| Endpoint | Method | Description | |
| 40 | +### 1. Multi-Tenancy (Root Only) |
| 41 | +| Endpoint | Method | Use Case | |
83 | 42 | | :--- | :--- | :--- | |
84 | | -| `/api/v1/config/settings` | GET | Get system configuration settings (admin only). | |
85 | | -| `/api/v1/config/settings` | PUT | Update system configuration settings (admin only). | |
86 | | - |
87 | | -### Federated Catalog Operations |
| 43 | +| `tenants` | GET/POST/PUT | Onboard new organizations to the platform. | |
| 44 | +| `config/settings` | GET/PUT | Manage global platform defaults. | |
88 | 45 |
|
89 | | -| Endpoint | Method | Description | |
| 46 | +### 2. Infrastructure & Data (Tenant Admin) |
| 47 | +| Endpoint | Method | Use Case | |
90 | 48 | | :--- | :--- | :--- | |
91 | | -| `/api/v1/federated-catalogs/{name}/sync` | POST | Trigger immediate metadata sync for federated catalog. | |
92 | | -| `/api/v1/federated-catalogs/{name}/stats` | GET | Get sync statistics and status for federated catalog. | |
| 49 | +| `warehouses` | GET/POST/PUT | Configure cloud storage containers (S3/GCS/Azure). | |
| 50 | +| `catalogs` | GET/POST/PUT | Create local or federated Iceberg catalogs. | |
| 51 | +| `audit` | GET/POST | Query standard or count audit logs. | |
| 52 | +| `maintenance` | POST | Trigger snapshot expiration or orphan file removal. | |
93 | 53 |
|
94 | | -### Data Explorer |
95 | | - |
96 | | -| Endpoint | Method | Description | |
| 54 | +### 3. Branching & Merging |
| 55 | +| Endpoint | Method | Use Case | |
97 | 56 | | :--- | :--- | :--- | |
98 | | -| `/api/v1/catalogs/{prefix}/namespaces/tree` | GET | Get hierarchical namespace tree structure for a catalog. | |
| 57 | +| `branches` | GET/POST | List or create feature/ingest branches. | |
| 58 | +| `branches/merge` | POST | Initiate a Git-like merge between two branches. | |
| 59 | +| `merge-operations` | GET | Track progress of active or past merges. | |
| 60 | +| `conflicts/{id}/resolve`| POST | Apply conflict resolution strategies (Source Wins/Target Wins). | |
99 | 61 |
|
100 | | -### OAuth |
| 62 | +--- |
101 | 63 |
|
102 | | -| Endpoint | Method | Description | |
103 | | -| :--- | :--- | :--- | |
104 | | -| `/oauth/authorize/{provider}` | GET | Initiate OAuth flow (Google, GitHub, etc.). | |
105 | | -| `/oauth/callback/{provider}` | GET | OAuth callback handler. | |
| 64 | +## 🧬 OAuth 2.0 Flow |
| 65 | +Pangolin supports Google, GitHub, and Microsoft OAuth. |
106 | 66 |
|
107 | | -## Auditing |
| 67 | +- **Initiate**: `GET /oauth/authorize/{provider}` |
| 68 | +- **Callback**: `GET /oauth/callback/{provider}` |
108 | 69 |
|
109 | | -| Endpoint | Method | Description | |
110 | | -| :--- | :--- | :--- | |
111 | | -| `/api/v1/audit-logs` | GET | Retrieve audit logs for the current tenant. | |
| 70 | +--- |
112 | 71 |
|
113 | | -## Other APIs |
| 72 | +## 🚀 Quick Integration |
| 73 | +To use the API, ensure you provide the `Authorization` header and the `X-Pangolin-Tenant` header (unless in `NO_AUTH` mode). |
114 | 74 |
|
115 | | -- **Credential Vending**: `/api/v1/credentials` (GET) |
116 | | -- **S3 Presigning**: `/api/v1/presign` (POST) |
117 | | -- **Business Metadata**: `/api/v1/metadata/search` (POST) |
118 | | -- **Access Requests**: `/api/v1/access-requests` (GET/POST) |
119 | | -- **App Config**: `/api/v1/app-config` (GET) |
| 75 | +```bash |
| 76 | +curl -X GET http://localhost:8080/api/v1/catalogs \ |
| 77 | + -H "Authorization: Bearer <JWT_TOKEN>" \ |
| 78 | + -H "X-Pangolin-Tenant: <TENANT_UUID>" |
| 79 | +``` |
0 commit comments