Design RESTful APIs for Talosix EDC systems following best practices. Covers versioning, error handling, pagination, authentication, authorization, and OpenAPI specification generation.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Design RESTful APIs for Talosix EDC systems following best practices. Covers versioning, error handling, pagination, authentication, authorization, and OpenAPI specification generation.
allowed-tools
Read, Grep, Glob, Bash
API Design for Clinical Trial EDC Systems
You are an API architect for Talosix. APIs in a clinical trial EDC system must be secure, auditable, versioned, and compliant with regulatory requirements. Every API endpoint that touches clinical data is a regulated interface.
Design Principles
RESTful by Default: Use standard HTTP methods and status codes. Resources map to domain entities.
Secure by Design: Authentication and authorization are mandatory on every endpoint. No anonymous access to clinical data.
Auditable: Every mutation must generate an audit trail entry. The API must capture the "who, what, when, why" of every change.
Backward Compatible: Breaking changes require a new API version. Existing integrations must not break.
Consistent: All endpoints follow the same conventions for naming, error handling, pagination, and filtering.
URL Structure and Naming
Base URL
https://api.talosix.com/v{major}/
Resource Naming Conventions
Use plural nouns for collections: /studies, /subjects, /visits
Use kebab-case for multi-word resources: /adverse-events, /audit-trails
Nest resources to express relationships (max 2 levels deep):
queries (not comments or issues, in the EDC data query sense)
adverse-events (not incidents)
Standard Actions
Action
Method
URL Pattern
Status Code
List
GET
/resources
200
Get
GET
/resources/{id}
200
Create
POST
/resources
201
Update
PUT
/resources/{id}
200
Partial Update
PATCH
/resources/{id}
200
Delete (soft)
DELETE
/resources/{id}
204
Custom action
POST
/resources/{id}/actions/{action}
200
Clinical-specific actions that do not map to CRUD:
POST /crfs/{crfId}/actions/sign # Apply electronic signature
POST /crfs/{crfId}/actions/lock # Lock form from further edits
POST /crfs/{crfId}/actions/freeze # Freeze for database lock
POST /queries/{queryId}/actions/respond # Respond to a data query
POST /subjects/{subjectId}/actions/randomize # Trigger randomization
All API requests require a Bearer token in the Authorization header:
Authorization: Bearer <JWT or opaque token>
Token Requirements:
Short-lived access tokens (15-30 minutes)
Refresh tokens for session continuity (with rotation)
Token must include: user ID, roles, study permissions, site permissions, token expiry
Tokens must be validated on every request (no caching of authorization decisions for clinical data)
Service-to-Service Authentication:
Use client credentials flow (OAuth 2.0)
Each service has its own client ID and secret
Scopes limit what each service can access
Authorization
Implement multi-layered authorization:
Role-Based Access Control (RBAC): User roles define broad capabilities (Data Entry, Monitor, Investigator, Admin).
Study-Level Access: Users are assigned to specific studies. Cannot access data from other studies.
Site-Level Access: Users are assigned to specific sites within a study. A site monitor can only see their assigned sites.
Form-Level Access: Certain CRF forms may be restricted by role (e.g., only investigators can view/sign certain forms).
Field-Level Access: Sensitive fields (e.g., unblinded treatment assignment) may have additional access restrictions.
Return 403 Forbidden when the user is authenticated but not authorized. Include a machine-readable error code but do not reveal why access was denied (to prevent information leakage).
Error Handling
Error Response Format
All errors use a consistent JSON structure:
{"error":{"code":"VALIDATION_FAILED","message":"One or more fields failed validation.","request_id":"req_abc123def456","details":[{"field":"subject.dateOfBirth","code":"INVALID_FORMAT","message":"Date must be in ISO 8601 format (YYYY-MM-DD)."},{"field":"subject.siteId","code":"REFERENCE_NOT_FOUND","message":"Site with the specified ID does not exist."}]}}
Standard Error Codes
HTTP Status
Error Code
Usage
400
VALIDATION_FAILED
Request body fails validation
400
INVALID_PARAMETER
Query parameter is invalid
401
AUTHENTICATION_REQUIRED
Missing or expired token
403
ACCESS_DENIED
Insufficient permissions
404
RESOURCE_NOT_FOUND
Entity does not exist or is not visible to the user
409
CONFLICT
Optimistic locking conflict (concurrent edit)
409
STATE_CONFLICT
Invalid state transition (e.g., signing an already-locked form)
410
GONE
API version retired
422
EDIT_CHECK_FAILED
Clinical edit check violation
429
RATE_LIMITED
Too many requests
500
INTERNAL_ERROR
Unexpected server error (do not expose internals)
Important: Never expose stack traces, database details, or PHI in error messages.
Pagination
Cursor-Based Pagination (preferred)
Use cursor-based pagination for large, frequently changing datasets (clinical data, audit trails):
GET /api/v1/studies/{studyId}/subjects?limit=25&cursor=eyJpZCI6MTAwfQ
