API Endpoints
This document defines the initial endpoint-level API contract for WildEditorInChief (WEIC).
The API exposes documents, revisions, fragments, tags, review actions, and publication actions through a resource-oriented service boundary. This document makes the API model more concrete by defining request patterns, response expectations, and status behavior.
This is an implementation-oriented document intended to guide backend and client development.
Purpose
The endpoint model exists to support several goals:
- define concrete resource paths
- define expected read and write behavior
- distinguish metadata updates from revision creation
- standardize response and error patterns
- provide a buildable API contract for WEIC implementation
The API contract should preserve the revision-first and governance-first rules defined elsewhere in the WEIC design.
General principles
The endpoint model follows several rules.
Metadata updates are separate from content revisions
Document and fragment metadata updates use metadata endpoints. Body content changes create new revisions.
Current state is pointer-based
Clients should not assume that body content is overwritten in place.
Revisions are explicit resources
Revision history is directly retrievable through revision endpoints.
Governance operations are explicit
Review and publication actions should not be hidden inside general update endpoints.
Common response expectations
Typical successful responses should include:
- resource identifiers
- current state metadata
- timestamps
- relevant linked state such as current revision id
Typical failure responses should include:
- error type
- message
- validation or authorization context where appropriate
Suggested common status codes:
| Code | Meaning |
|---|---|
| 200 | successful retrieval or update |
| 201 | resource created |
| 400 | invalid request |
| 401 | unauthenticated |
| 403 | authenticated but unauthorized |
| 404 | resource not found |
| 409 | conflict |
| 422 | semantically invalid content |
| 500 | internal server error |
Document endpoints
List documents
GET /api/documents
Purpose:
- retrieve documents
- support filtering or hierarchy views later
Suggested response fields:
- id
- parent_id
- title
- slug
- owner
- status
- current_revision_id
- created_utc
- updated_utc
Create document
POST /api/documents
Suggested request body:
{
"parent_id": "ROOT",
"title": "Security Policy",
"slug": "security-policy",
"owner": "robert",
"status": "draft"
}
Suggested response:
- created document metadata
- current_revision_id may be null until first revision exists
Typical status:
201 Created
Get document
GET /api/documents/{id}
Purpose:
- retrieve stable document metadata
- optionally include current revision summary or body where configured
Typical status:
200 OK404 Not Found
Update document metadata
PATCH /api/documents/{id}
Purpose:
- update metadata only
Allowed examples:
- title
- slug
- owner
- status
- parent_id
Not allowed here:
body_html
Suggested request body:
{
"title": "Updated Security Policy",
"status": "review"
}
Typical status:
200 OK400 Bad Request403 Forbidden
Document revision endpoints
List document revisions
GET /api/documents/{id}/revisions
Purpose:
- retrieve revision history for a document
Suggested response fields:
- revision id
- author
- revision_note
- created_utc
Create document revision
POST /api/documents/{id}/revisions
Purpose:
- create a new content revision
- optionally make it current immediately depending on workflow rules
Suggested request body:
{
"body_html": "<p>Updated policy content</p>",
"revision_note": "Aligned with revised architecture model"
}
Typical response fields:
- revision id
- document id
- created_utc
- author
- body_html
- revision_note
Typical status:
201 Created422 Unprocessable Entityfor invalid content payload
Get specific document revision
GET /api/documents/{id}/revisions/{revisionId}
Purpose:
- retrieve one historical content state
Typical response:
- full revision details including
body_html
Fragment endpoints
List fragments
GET /api/fragments
Create fragment
POST /api/fragments
Suggested request body:
{
"name": "Standard Disclaimer"
}
Get fragment
GET /api/fragments/{id}
Update fragment metadata
PATCH /api/fragments/{id}
Purpose:
- update metadata such as
name - not fragment body content
Suggested request body:
{
"name": "Updated Standard Disclaimer"
}
Fragment revision endpoints
List fragment revisions
GET /api/fragments/{id}/revisions
Create fragment revision
POST /api/fragments/{id}/revisions
Suggested request body:
{
"body_html": "<p>Reusable approved language</p>",
"revision_note": "Clarified standard wording"
}
Get specific fragment revision
GET /api/fragments/{id}/revisions/{revisionId}
Tag endpoints
List tags
GET /api/tags
Create tag
POST /api/tags
Suggested request body:
{
"name": "security"
}
List document tags
GET /api/documents/{id}/tags
Attach tag to document
POST /api/documents/{id}/tags
Suggested request body:
{
"tag_id": "tag-security"
}
Remove tag from document
DELETE /api/documents/{id}/tags/{tagId}
Review endpoints
List reviews for a document
GET /api/documents/{id}/reviews
Create or record a review decision for a revision
POST /api/documents/{id}/revisions/{revisionId}/reviews
POST /api/fragments/{id}/revisions/{revisionId}/reviews
Suggested request body:
{
"status": "approved",
"review_note": "Content approved for publication"
}
Typical statuses:
201 Created400 Bad Request403 Forbidden
Publication endpoints
List publication records
GET /api/documents/{id}/publications
GET /api/fragments/{id}/publications
Publish a revision
POST /api/documents/{id}/revisions/{revisionId}/publish
POST /api/fragments/{id}/revisions/{revisionId}/publish
Suggested request body:
{
"channel": "internal",
"publication_note": "Approved for internal publication"
}
Typical response:
- publication id
- target id
- revision id
- published_utc
- published_by
- channel
Search endpoint (future-ready)
A future search endpoint may take the form:
GET /api/search?q=...
This is not required for the first implementation, but the endpoint model should leave room for it.
Validation rules
Important validation rules include:
- metadata update endpoints must reject body content updates
- revision creation endpoints require
body_html - tag creation should reject duplicate tag names
- review endpoints should reject unknown statuses
- publish endpoints should reject invalid revision identifiers
- slugs should meet application naming rules
Validation belongs in the API layer so clients receive predictable behavior.
Example separation rule
The API contract should make the following rule explicit:
PATCH /api/documents/{id}
PATCH /api/fragments/{id}
update metadata only.
POST /api/documents/{id}/revisions
POST /api/fragments/{id}/revisions
create content revisions.
This is one of the most important behaviors in the WEIC API design.
Relationship to the Oryvin plan
The endpoint model is one of the implementation bridges between architecture and code.
WEIC storage and governance model
↓
concrete API endpoints
↓
backend implementation and client integration
This is where the knowledge platform becomes directly buildable as a service.