Swagger
This section provides details on how to access and use the Swagger documentation for SolidX REST APIs.
API Documentation
SolidX automatically generates API documentation for your endpoints using Swagger and the OpenAPI specification. Swagger UI gives developers an interactive surface to inspect routes, payloads, and auth-protected requests without leaving the browser.
Mental Model
Swagger is the fastest way to inspect what the current backend actually exposes. Treat it as a live contract viewer for generated and extended endpoints, not just a passive reference page.
Accessing API Documentation
Navigate to your SolidX installation.
Go to the /docs endpoint of your solid api runtime.
You will see the Swagger UI with all available endpoints.
Authentication
Before using the APIs, authenticate and pass the returned bearer token with protected requests:
Use the /api/iam/authenticate endpoint.
Provide your credentials.
Receive a JWT token in the form of an access token.
Use this token in the Authorization header for subsequent requests.
Example Authentication Flow
POST /api/auth/login
{
"email": "user@example.com",
"password": "yourpassword"
}{
"token": "***********************",
"user": {
"id": 1,
"email": "user@example.com"
// ...
}
}API Structure
Resource Endpoints
Each resource in a SolidX app automatically gets the following RESTful endpoints:
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/{resource} | List resources |
| GET | /api/{resource}/{id} | Get single resource |
| POST | /api/{resource} | Create resource |
| PUT | /api/{resource}/{id} | Update resource |
| PATCH | /api/{resource}/{id} | Partially update resource |
| DELETE | /api/{resource}/{id} | Delete resource |
Query Parameters
The list endpoint supports various query parameters:
| Parameter | Description | Example |
|---|---|---|
| filters | Filter records | ?filters[status]=active |
| sort | Sort records | ?sort=created_at:desc |
| pagination | Paginate results | ?page=1&limit=10 |
| populate | Include relationships | ?populate=author,comments |
| fields | Select specific fields | ?fields=title,content |
Example Requests
GET /api/posts?filters[status]=published&sort=created_at:descPOST /api/posts
{
"title": "New Post",
"content": "Post content",
"status": "draft"
}PUT /api/posts/1
{
"status": "published"
}Error Handling
All API errors follow a consistent format:
{
"error": {
"status": 400,
"name": "ValidationError",
"message": "Title is required",
"details": {
"fields": {
"title": ["This field is required"]
}
}
}
}Common Error Codes
| Code | Description |
|---|---|
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Authentication required |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource doesn't exist |
| 422 | Unprocessable Entity - Validation failed |
| 500 | Internal Server Error |
Best Practices
- Authentication: Use HTTPS, keep tokens secure, and verify protected routes with a real bearer token before testing downstream APIs.
- Request Optimization: Use field selection, pagination, relation population, and filter parameters deliberately so large resources stay easy to inspect.
- Error Handling: Use Swagger to validate request shape, inspect error payloads, and confirm that status codes match the intended runtime behavior.
- Documentation: Keep examples aligned with real payloads and use the live docs as the quickest checkpoint after metadata or backend extension changes.