ver 1.0.0 initial commit

2026-06-27 17:25:55 -05:00
parent 550111295a
commit 2a7efe9c5d
20 changed files with 1850 additions and 0 deletions
@@ -0,0 +1,60 @@
+# OpenProject API v3 endpoint map
+
+Base: `<server>/api/v3`. Auth: HTTP Basic, username `apikey`, password = API token
+(the CLI handles this). Responses are HAL+JSON: `_type`, `_links`, `_embedded`.
+Collections carry `total`, `count`, `pageSize`, and `_embedded.elements`.
+
+Endpoints the `op.py` CLI wraps directly are marked ✅. Everything else is reachable
+via `op.py raw <METHOD> <path> [--data '{...}']`.
+
+## Work packages
+- ✅ `GET    /work_packages` — list/filter (also `/projects/{id}/work_packages`)
+- ✅ `GET    /work_packages/{id}` — single
+- ✅ `POST   /work_packages` — create
+- ✅ `PATCH  /work_packages/{id}` — update (needs `lockVersion`; CLI auto-fetches)
+- ✅ `DELETE /work_packages/{id}` — delete
+- ✅ `POST   /work_packages/{id}/activities` — add comment
+- `GET    /work_packages/{id}/activities` — comment/change history
+- `GET    /work_packages/{id}/relations` · `POST /relations` — links between WPs
+- `GET    /work_packages/{id}/watchers` · `POST .../watchers`
+- `GET    /work_packages/form` · `POST /work_packages/{id}/form` — field schema/validation
+- `GET    /work_packages/schemas` — allowed values per project+type
+
+## Projects
+- ✅ `GET  /projects` — list/filter (`name_and_identifier` filter)
+- ✅ `GET  /projects/{id}` — single (id or identifier)
+- `POST   /projects` · `PATCH /projects/{id}` · `DELETE /projects/{id}`
+- ✅ `GET  /projects/{id}/types` — types enabled in a project
+- `GET    /projects/{id}/versions` — versions/milestones
+- `GET    /projects/{id}/categories`
+- `GET    /projects/{id}/memberships`
+
+## People & metadata
+- ✅ `GET  /users/me` — current user (`ping`/`me`)
+- ✅ `GET  /users` — list/filter
+- `GET    /groups` · `GET /roles`
+- ✅ `GET  /types` · `GET /statuses` · `GET /priorities`
+- `GET    /time_entries/activities` — activity types for time logging
+
+## Time tracking
+- ✅ `POST /time_entries` — log time (`hours` is ISO-8601 duration, e.g. `PT1H30M`;
+  CLI accepts a plain number of hours and converts)
+- `GET    /time_entries` — list/filter
+- `PATCH  /time_entries/{id}` · `DELETE /time_entries/{id}`
+
+## Other useful resources
+- `GET /queries` · `GET /queries/{id}` — saved views (filters+columns+sort)
+- `GET /versions/{id}` — milestone detail
+- `GET /attachments/{id}` · `POST /work_packages/{id}/attachments` — files
+- `GET /notifications` — in-app notifications
+- `GET /memberships` — project membership management
+
+## Notes
+- **lockVersion / optimistic locking:** any `PATCH` to a work package must include the
+  `lockVersion` you got from the last `GET`. If it's stale, the API returns `409`/`422`
+  — re-fetch and retry. The CLI does this automatically for `wp update`/`wp close`.
+- **Durations:** time values use ISO-8601 (`PT1H`, `PT30M`, `P1DT2H`). The CLI's
+  `time log --hours 1.5` emits `PT1.5H`.
+- **Markdown fields:** `description` and `comment` take `{"format":"markdown","raw":"..."}`.
+- **Form endpoints** (`POST .../form`) validate a payload and return allowed values
+  without persisting — handy when unsure which statuses/types are valid for a project.