jacob-mathison/query-orchestration
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity
Files
3bdc27f4de4c73168b85e06de786226dbfb3b0d5
query-orchestration/queryapi.summary.md
T
Jay Brown c45e1dd427 Merged in feature/textExtractionsPart1 (pull request #192) 
all schema and rest apis for text extraction support

* in progress

* stage 8 complete

* phase 9 completed

* phase 9 complete

* ongoing - s3 path fix

* working

* optimize ci build

* e2e tests

* missing test
2025-11-26 19:23:42 +00:00

233 lines
10 KiB
Markdown
Raw Blame History

# Query API Endpoints Summary
This document provides a comprehensive summary of all REST API endpoints available in the Query Orchestration Platform.
## Authentication Service
### OAuth2 Authentication Flow
- **GET /login** - Initiate login flow by redirecting to Cognito IDP
- Redirects to AWS Cognito login page
- No authentication required
- **GET /login-callback** - Handle OAuth2 callback and exchange code for tokens
- Query Parameters:
- `code` (required) - Authorization code from Cognito
- `state` (required) - CSRF protection parameter
- Sets JWT cookie and redirects to dashboard
- **GET /logout** - Logout user and invalidate session
- Requires authentication
- Redirects to Cognito logout page or application home
- **GET /home** - Get the home page menu for authenticated users
- Requires authentication
- Returns HTML content for authenticated user menu
## Client Service
### Client Management
- **POST /client** - Create a new client with provided details
- Request Body: `{id, name}`
- Returns: `{id}` (201 Created)
- **GET /client/{id}** - Get a specific client by its ID
- Returns: `{id, name, can_sync}` (200 OK)
- **PATCH /client/{id}** - Update an existing client with new details
- Request Body: `{name?, can_sync?}` (optional fields)
- Returns: 200 OK on success
- **GET /client/{id}/status** - Retrieve the sync status for a client
- Returns: `{status}` where status is one of: `IN_SYNC`, `NOT_SYNCED`, `NOT_SYNCING`
## Collector Service
### Collector Configuration Management
- **GET /client/{id}/collector** - Get a collector configuration by client ID
- Returns: `{client_id, active_version, latest_version, minimum_cleaner_version, minimum_text_version, fields[]}`
- **PATCH /client/{id}/collector** - Set or update collector configuration for a client
- Request Body: `{minimum_cleaner_version?, minimum_text_version?, active_version?, fields[]?}`
- Returns: 204 No Content on success
## Documents Service
### Document Management
- **GET /client/{id}/document** - List all documents for a specific client
- Returns: Array of `{id, hash}` document summaries
- **POST /client/{id}/document** - Upload a single PDF file for a client
- Content-Type: `multipart/form-data`
- Form Data:
- `file` (required) - PDF file to upload (binary)
- `filename` (optional) - Custom filename (max 4096 chars)
- Returns: 200 OK on successful upload
- **GET /document/{id}** - Get document details by its ID
- Returns: `{id, client_id, hash, fields{}}`
### Batch Document Processing
- **POST /client/{id}/document/batch** - Upload multiple PDFs as ZIP archive for batch processing
- Content-Type: `multipart/form-data`
- Form Data:
- `archive` (required) - ZIP file containing PDF documents (max 1GB)
- Returns: `{batch_id, status, status_url}` (202 Accepted)
- **GET /client/{id}/document/batch** - List batch uploads for a client with pagination
- Query Parameters:
- `limit` (optional, default: 20, max: 100) - Number of items to return
- `offset` (optional, default: 0) - Number of items to skip
- Returns: `{batches[], total_count}`
- **GET /client/{id}/document/batch/{batch_id}** - Get detailed status of a specific batch upload
- Returns: `{batch_id, client_id, original_filename, status, total_documents, processed_documents, failed_documents, invalid_type_documents, progress_percent, created_at, completed_at?, failed_filenames[]}`
- **DELETE /client/{id}/document/batch/{batch_id}** - Cancel a batch upload currently processing
- Returns: 204 No Content on successful cancellation
## Query Service
### Query Definition and Execution
- **GET /query** - List queries based on filter criteria
- Returns: `{queries[]}` where each query contains `{id, type, active_version, latest_version, config?, required_queries[]?}`
- **POST /query** - Create a new query with provided details
- Request Body: `{type, config?, required_queries[]?}`
- Supported Types: `JSON_EXTRACTOR`, `CONTEXT_FULL`
- Returns: `{id}` (201 Created)
- **GET /query/{id}** - Get a specific query by its ID
- Returns: `{id, type, active_version, latest_version, config?, required_queries[]?}`
- **PATCH /query/{id}** - Update an existing query with new details
- Request Body: `{config?, active_version?, required_queries[]?}`
- Returns: 200 OK on success
- **POST /query/{id}/test** - Execute a test run of a query with parameters
- Request Body: `{document_id, query_version}`
- Returns: `{value}` - Result of the query test
## Export Service
### Export Management
- **POST /client/{id}/export** - Trigger an export process for a client
- Request Body: `{ingestion_filters?, field_filters[]?}`
- Ingestion Filters: `{start_date?, end_date?}`
- Field Filters: `{field_name, condition, values[]}`
- Conditions: `less_than`, `greater_than`, `closed_interval`, `open_interval`, `left_closed_interval`, `right_closed_interval`, `include`, `exclude`
- Returns: `{id}` (201 Created)
- **GET /export/{id}** - Check the current state of an export
- Returns: `{client_id, status, output_location?}`
- Status values: `completed`, `in_progress`, `failed`
## Admin Service
### User Management
#### User Creation and Listing
- **POST /admin/users** - Create a new user
- Request Body: `{email, first_name, last_name, roles[]}`
- Creates user in both AWS Cognito and Permit.io
- Roles: Must exist in Permit.io (e.g., `super_admin`, `user_admin`, `auditor`, `client_user`)
- Returns: `{cognito_subject_id, email, first_name, last_name, status, enabled, permit_synced, roles_assigned[], created_at}` (201 Created or 200 OK if already exists)
- **Idempotent**: Returns 200 OK if user already exists with matching attributes
- **GET /admin/users** - List users with pagination, filtering, and sorting
- Query Parameters:
- `page` (optional, default: 1, max: 10000) - Page number
- `page_size` (optional, default: 50, max: 100) - Results per page
- `search` (optional) - Search term for email/name filtering
- `status` (optional, default: `all`) - Filter by status: `enabled`, `disabled`, `all`
- `sort_by` (optional, default: `email`) - Sort field: `email`, `created_at`, `last_name`
- `sort_order` (optional, default: `asc`) - Sort direction: `asc`, `desc`
- Returns: `{users[], total, page, page_size, has_more}`
#### Individual User Operations
- **GET /admin/users/{email}** - Get user by email
- Returns: `{cognito_subject_id, email, first_name, last_name, status, enabled, roles[], created_at, updated_at}`
- **HEAD /admin/users/{email}** - Check if user exists
- Returns: 200 OK with headers:
- `X-User-Exists-Cognito: boolean` - Whether user exists in Cognito
- `X-User-Exists-PermitIO: boolean` - Whether user exists in Permit.io
- Returns: 404 Not Found if user doesn't exist in either system
- **PATCH /admin/users/{email}** - Update user attributes and roles
- Request Body: `{first_name?, last_name?, roles[]?}`
- **Role Management**: Providing `roles[]` REPLACES all existing roles (not additive)
- To add a role: Include all current roles PLUS the new role
- To remove a role: Include only roles you want to keep
- To remove all roles: Send empty array `[]`
- Omit `roles` field to leave roles unchanged
- Returns: `{cognito_subject_id, email, first_name, last_name, status, enabled, roles[], created_at, updated_at}` (200 OK)
- **DELETE /admin/users/{email}** - Delete user permanently
- Query Parameters:
- `confirm=true` (required) - Must be set to confirm deletion
- Deletes from both AWS Cognito and Permit.io
- **Irreversible operation**
- Returns: `{success, email, cognito_subject_id, deleted_from{cognito, permit}, timestamp}` (200 OK or 207 Multi-Status for partial deletion)
#### User Account Status Management
- **POST /admin/users/{email}/disable** - Disable user
- Disables user in AWS Cognito, preventing authentication
- User data and roles are preserved
- **Idempotent**: Safe to call multiple times
- Returns: `{success, email, action, cognito_subject_id, timestamp}` (200 OK)
- **POST /admin/users/{email}/enable** - Enable user
- Re-enables a previously disabled user in AWS Cognito
- Restores authentication capability
- **Idempotent**: Safe to call multiple times
- Returns: `{success, email, action, cognito_subject_id, timestamp}` (200 OK)
## Common Response Codes
All endpoints may return the following standard HTTP response codes:
- **200 OK** - Request succeeded
- **201 Created** - Resource created successfully
- **202 Accepted** - Request accepted for async processing
- **204 No Content** - Request succeeded with no response body
- **207 Multi-Status** - Partial success (e.g., deletion from only one system)
- **302 Found** - Redirect (for auth flows)
- **400 Bad Request** - Invalid request body or parameters
- **401 Unauthorized** - Authentication required or failed
- **403 Forbidden** - Insufficient permissions
- **404 Not Found** - Resource does not exist
- **409 Conflict** - Resource already exists or state conflict
- **429 Too Many Requests** - Rate limit exceeded (includes `Retry-After` header)
- **500 Internal Server Error** - Server-side error
- **502 Bad Gateway** - External service error (e.g., Cognito, Permit.io)
## Rate Limiting
All endpoints implement dual-layer rate limiting:
- **Global Rate Limit**: 500 requests/second across all IPs (1000 burst)
- **Per-IP Rate Limit**: 5 requests/second per IP (10 burst)
Rate limit headers included in all responses:
- `RateLimit: limit;window=time-window` (e.g., `100;window=60`)
- `Retry-After: seconds` (only on 429 responses)
## Security
- **Authentication**: JWT Bearer tokens via AWS Cognito OAuth2
- **Authorization**: Role-based access control (RBAC) via Permit.io
- **All endpoints require authentication** except:
- `GET /login` - Public login initiation
- `GET /login-callback` - OAuth2 callback handler
## API Versioning
- **Base URL**: `https://doczy.com/v1` (production)
- **Local Development**: `http://localhost:8080`
- **API Version**: 0.0.1
- **OpenAPI Specification**: `serviceAPIs/queryAPI.yaml`
## Documentation
- **Swagger UI**: Available at `/swagger/index.html` when running locally
- **OpenAPI Spec**: Auto-generated from `serviceAPIs/queryAPI.yaml`
Reference in New Issue View Git Blame Copy Permalink