This document describes the OpenAPI specification that serves as the central contract for the entire RealWorld ecosystem. The specification defines all API endpoints, data models, authentication mechanisms, and response formats that enable any frontend implementation to work with any backend implementation.
For details about the reference implementation that demonstrates these specifications in practice, see Reference Implementation. For information about testing implementations against this specification, see Testing Infrastructure. For frontend-specific integration guidance, see Frontend API Integration Guide.
The RealWorld API specification is the most critical component of the entire project (importance: 358.95). It is formally defined using the OpenAPI 3.1.0 standard and serves as the single source of truth that enables over 150 frontend and backend implementations to work interchangeably. This specification-driven architecture allows developers to swap out any frontend with any backend, as long as both adhere to the contract.
The specification is maintained in api/openapi.yml and defines 19 distinct API endpoints organized into 6 functional categories: User and Authentication, Profile, Articles, Comments, Favorites, and Tags.
Sources: README.md1-42 api/openapi.yml1-919
Specification File Structure
The OpenAPI specification follows a hierarchical structure that organizes all API contract information into well-defined sections. Understanding this structure is essential for implementing compliant backends or consuming the API from frontends.
Sources: api/openapi.yml1-919
The specification defines 19 endpoints organized into 6 functional categories. Each endpoint specifies the HTTP method, path parameters, query parameters, request body schema, response schemas, and authentication requirements.
| Category | Endpoints | Authentication Required |
|---|---|---|
| User and Authentication | POST /users/loginPOST /usersGET /userPUT /user | Login/Register: No Get/Update: Yes |
| Profile | GET /profiles/{username}POST /profiles/{username}/followDELETE /profiles/{username}/follow | Get: Optional Follow/Unfollow: Yes |
| Articles | GET /articlesGET /articles/feedPOST /articlesGET /articles/{slug}PUT /articles/{slug}DELETE /articles/{slug} | List/Get: Optional Feed/Create/Update/Delete: Yes |
| Comments | GET /articles/{slug}/commentsPOST /articles/{slug}/commentsDELETE /articles/{slug}/comments/{id} | Get: Optional Create/Delete: Yes |
| Favorites | POST /articles/{slug}/favoriteDELETE /articles/{slug}/favorite | Yes |
| Tags | GET /tags | No |
Sources: api/openapi.yml21-453
Mapping Example: GET /articles Endpoint
The specification defines the endpoint at api/openapi.yml181-213 with query parameters for filtering (tag, author, favorited) and pagination (offset, limit). The reference implementation handles this in apps/api/server/routes/api/articles/index.get.ts1-115 where the buildFindAllQuery function processes these parameters and constructs Prisma queries. The Postman collection validates the implementation at api/Conduit.postman_collection.json349-419 with assertions checking response structure and data types.
Sources: api/openapi.yml181-213 apps/api/server/routes/api/articles/index.get.ts1-115 api/Conduit.postman_collection.json349-419
The specification defines comprehensive schemas for all data types in the components.schemas section. These schemas enforce data consistency across all implementations and define required fields, data types, and validation rules.
Schema Organization
All schemas are defined in api/openapi.yml455-644 and follow consistent patterns:
{ "user": User }, { "article": Article })Sources: api/openapi.yml455-644
The specification defines JWT-based authentication using the Token security scheme. This scheme is declared in api/openapi.yml909-918 and specifies that protected endpoints must include an Authorization header with the format:
Authorization: Token xxxxxx.yyyyyyy.zzzzzz
Authentication Specification
Endpoints that require authentication declare security: [{ Token: [] }] in their definition. Some endpoints like GET /articles and GET /profiles/{username} have optional authentication, meaning they work without a token but may return different data when authenticated (e.g., favorited and following flags).
Sources: api/openapi.yml909-918 api/openapi.yml69-70 api/openapi.yml86-87
The specification defines standardized response structures for both successful operations and errors in the components.responses section.
| Response Type | HTTP Status | Structure |
|---|---|---|
UserResponse | 200/201 | { "user": User } |
ProfileResponse | 200 | { "profile": Profile } |
SingleArticleResponse | 200/201 | { "article": Article } |
MultipleArticlesResponse | 200 | { "articles": Article[], "articlesCount": integer } |
SingleCommentResponse | 200/201 | { "comment": Comment } |
MultipleCommentsResponse | 200 | { "comments": Comment[] } |
TagsResponse | 200 | { "tags": string[] } |
EmptyOkResponse | 204 | No content |
Unauthorized | 401 | { "errors": { "token": ["is missing"] } } |
Forbidden | 403 | { "errors": { "resource": ["forbidden"] } } |
NotFound | 404 | { "errors": { "resource": ["not found"] } } |
ConflictError | 409 | { "errors": { "username": ["has already been taken"] } } |
GenericError | 422 | { "errors": { "field": ["error message"] } } |
Error Response Schema
All error responses use the GenericErrorModel schema defined in api/openapi.yml633-643 which has a consistent structure:
This allows multiple validation errors to be returned in a single response, with each field containing an array of error messages.
Sources: api/openapi.yml645-816 api/openapi.yml633-643
The specification declares version 2.0.0 in api/openapi.yml11 and follows semantic versioning principles:
The hosted API at https://api.realworld.show/api (defined in api/openapi.yml20) maintains compatibility with all implementations built against the current major version.
Sources: api/openapi.yml1-21
Implementation Workflow
GenericErrorModel schemaSources: api/openapi.yml1-919 api/README.md1-12 api/Conduit.postman_collection.json1-50
The specification defines a default server at https://api.realworld.show/api in api/openapi.yml19-20 This hosted API provides:
Frontend implementations can override this base URL to point to:
http://localhost:3000/api)Sources: api/openapi.yml19-20 apps/documentation/src/content/docs/specifications/frontend/api.md1-55 README.md34-35
The specification defines reusable parameter schemas in the components.parameters section:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
offset | integer | No | 0 | Number of items to skip before collecting results |
limit | integer | No | 20 | Number of items to return (minimum: 1) |
These parameters are used in list endpoints like GET /articles and GET /articles/feed to implement pagination. The articlesCount field in the response always contains the total count of articles matching the query, not the number of items returned in the current page.
Sources: api/openapi.yml891-907 api/Conduit.postman_collection.json782-874
The API specification exists in multiple formats across the repository:
Sources: api/openapi.yml1-919 apps/documentation/src/assets/swagger.json1-1143 api/Conduit.postman_collection.json1-50 api/README.md1-12
Refresh this wiki