This page explains how frontend implementations integrate with RealWorld backends through the standardized API. It covers backend deployment options, request formatting, authentication patterns, and the visibility restrictions in the limited branch. For details on the API specification itself, see OpenAPI Specification Structure. For authentication implementation details in the reference backend, see Authentication Implementation.
Frontend implementations in the RealWorld ecosystem can connect to any compliant backend. Three primary deployment strategies are supported:
Sources: README.md34-35 apps/documentation/src/content/docs/specifications/frontend/api.md5-39
All API endpoints are prefixed with /api after the base domain. The complete URL structure follows this pattern:
| Deployment Type | Base URL | Example Full Endpoint |
|---|---|---|
| Local Development | http://localhost:3000/api | http://localhost:3000/api/articles |
| Public Hosted API | https://api.realworld.show/api | https://api.realworld.show/api/articles |
| Custom Hosted | https://your-domain.com/api | https://your-domain.com/api/articles |
The OpenAPI specification defines the server URL at apps/documentation/src/assets/swagger.json36-40:
"servers": [
{
"url": "https://api.realworld.show/api"
}
]
Sources: apps/documentation/src/assets/swagger.json36-40 apps/documentation/src/content/docs/specifications/frontend/api.md39
Sources: apps/documentation/src/assets/swagger.json41-632 apps/documentation/src/assets/swagger.json1133-1140
The API uses JWT-based authentication with a custom header format. After successful login or registration, the backend returns a JWT token that must be included in subsequent authenticated requests.
Token Format in Authorization Header:
Authorization: Token xxxxxx.yyyyyyy.zzzzzz
Note the prefix is Token (not Bearer as is common in many APIs). This is specified in the OpenAPI security scheme at apps/documentation/src/assets/swagger.json1134-1139:
"Token": {
"type": "apiKey",
"description": "For accessing the protected API resources...",
"name": "Authorization",
"in": "header"
}
| Authentication | Endpoints |
|---|---|
| Required | POST /api/articles, PUT /api/articles/{slug}, DELETE /api/articles/{slug}, POST /api/articles/{slug}/comments, DELETE /api/articles/{slug}/comments/{id}, POST /api/articles/{slug}/favorite, DELETE /api/articles/{slug}/favorite, POST /api/profiles/{username}/follow, DELETE /api/profiles/{username}/follow, GET /api/user, PUT /api/user, GET /api/articles/feed |
| Optional | GET /api/articles, GET /api/articles/{slug}, GET /api/articles/{slug}/comments, GET /api/profiles/{username} |
| Not Required | POST /api/users/login, POST /api/users, GET /api/tags |
Endpoints marked as optional will return personalized data (e.g., favorited: true, following: true) when authenticated, but work without authentication.
Sources: apps/documentation/src/assets/swagger.json101-105 apps/documentation/src/assets/swagger.json1134-1139
The reference implementation repository maintains two branches with different purposes:
Sources: apps/documentation/src/content/docs/specifications/frontend/api.md17-19 apps/documentation/src/content/docs/specifications/frontend/api.md26-34
The limited branch implements visibility restrictions to prevent abuse and inappropriate content exposure in public deployments. These limitations are documented at apps/documentation/src/content/docs/specifications/frontend/api.md45-55
Visibility Matrix:
| User State | Visible Content |
|---|---|
| Logged Out | Only content created by demo accounts |
| Logged In | Own content + content created by demo accounts |
These limitations ensure:
Sources: apps/documentation/src/content/docs/specifications/frontend/api.md45-55
The public hosted API is available at https://api.realworld.show/api. This deployment:
limited branch with visibility restrictionshttps://demo.realworld.show (README.md35)As stated in apps/documentation/src/content/docs/specifications/frontend/api.md42-43:
The API is freely available for public usage but its access is limited to RealWorld usage only: you won't be able to consume it on its own but with a frontend application.
This means the API is designed to be accessed through browser-based frontend implementations that follow the RealWorld specification, not for standalone API consumption or scripting.
Sources: README.md34-35 apps/documentation/src/content/docs/specifications/frontend/api.md36-43
All request bodies follow the wrapper pattern where the data is nested under a key matching the resource type. This is defined in the OpenAPI specification at apps/documentation/src/assets/swagger.json1006-1108
User Registration:
User Login:
Create Article:
Create Comment:
Sources: apps/documentation/src/assets/swagger.json1006-1108
Responses also follow the wrapper pattern. Successful responses wrap data under resource-specific keys as defined at apps/documentation/src/assets/swagger.json862-1005
User Response (Login/Register):
Single Article Response:
Multiple Articles Response:
Error Response:
Sources: apps/documentation/src/assets/swagger.json862-1005 apps/documentation/src/assets/swagger.json843-860
For frontend developers creating new RealWorld implementations:
Start with Local Backend: Use the reference implementation's main branch running locally on port 3000 for initial development. See Running Locally for setup instructions.
Test Against Public API: Once basic functionality works, test against https://api.realworld.show/api to verify behavior with the limited branch restrictions.
Consider Custom Hosting: For production deployments, deploy your own backend instance using the limited branch to maintain full control over data and avoid shared account isolation.
The complete API specification is available in OpenAPI 3.0.1 format at apps/documentation/src/assets/swagger.json1-1143 This file defines all 15 endpoints, request/response schemas, and authentication requirements. Frontend developers should reference this specification when implementing API calls.
Sources: apps/documentation/src/content/docs/specifications/frontend/api.md1-55 README.md32-36
Refresh this wiki