wip

2026-09-03 17:56:47 +03:00
commit 33490da091
136 changed files with 20062 additions and 0 deletions
@@ -0,0 +1,102 @@
+# api-basics
+
+Core conventions for the Prisma Management API. All three `prisma-postgres-*` skills share these patterns.
+
+## Base URL
+
+```
+https://api.prisma.io/v1
+```
+
+API documentation: https://api.prisma.io/v1/doc
+
+## Response Envelope
+
+### Single resource
+
+```json
+{
+  "data": {
+    "id": "proj_clx7abc123def456",
+    "type": "project",
+    "name": "My Project",
+    "createdAt": "2025-06-15T10:30:00.000Z"
+  }
+}
+```
+
+### Collection
+
+```json
+{
+  "data": [
+    { "id": "proj_aaa", "type": "project", "name": "Alpha" },
+    { "id": "proj_bbb", "type": "project", "name": "Beta" }
+  ],
+  "pagination": {
+    "hasMore": true,
+    "nextCursor": "clx7cursor123"
+  }
+}
+```
+
+## Resource ID Prefixes
+
+Every resource ID carries a type prefix:
+
+| Prefix | Resource |
+|---|---|
+| `proj_` | Project |
+| `db_` | Database |
+| `con_` | Connection |
+| `wksp_` | Workspace |
+
+Always include the prefix when sending IDs in API requests.
+
+## Pagination
+
+Collection endpoints use cursor-based pagination:
+
+```
+GET /v1/projects?limit=10
+GET /v1/projects?cursor=clx7abc123&limit=10
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `cursor` | string | — | Opaque cursor from `nextCursor` |
+| `limit` | number | 100 | Maximum items per page |
+
+Continue fetching while `pagination.hasMore` is `true`, using `pagination.nextCursor` as the `cursor` parameter.
+
+## Error Responses
+
+All errors follow this shape:
+
+```json
+{
+  "error": {
+    "code": "resource-not-found",
+    "message": "database with id db_abc not found"
+  }
+}
+```
+
+### Error codes by HTTP status
+
+| HTTP Status | Error Code | Meaning |
+|---|---|---|
+| 400 | `client-error` | Malformed request |
+| 401 | `authentication-failed` | Missing or invalid token |
+| 403 | `permission-denied` | Token lacks required access |
+| 404 | `resource-not-found` | Resource does not exist or is not accessible |
+| 422 | `validation-error` | Request body failed validation |
+| 429 | `rate-limit-exceeded` | Too many requests |
+| 500 | `internal-server-error` | Server error — retry after a delay |
+
+### Self-correction patterns
+
+- **401**: Token is invalid or expired. Create a new service token in Console → Workspace Settings → Service Tokens.
+- **404**: Verify the resource ID includes the correct prefix (`proj_`, `db_`, `con_`). Use `GET /v1/projects` or `GET /v1/databases` to list available resources.
+- **422**: Check the request body against the endpoint schema. Common issues: missing required fields, invalid region ID, empty `name`.
+- **429**: Wait 2–5 seconds and retry. If repeated, increase the backoff interval.