RealWorld API Spec
Running API tests locally
To locally run the provided Postman collection against your backend, execute:
For more details, see run-api-tests.sh
.
Considerations for your backend with CORS
If the backend is about to run on a different host/port than the frontend, make sure to handle OPTIONS
too and return correct Access-Control-Allow-Origin
and Access-Control-Allow-Headers
(e.g. Content-Type
).
Authentication Header:
Authorization: Token jwt.token.here
JSON Objects returned by API:
Make sure the right content type like Content-Type: application/json; charset=utf-8
is correctly returned.
Users (for authentication)
Profile
Single Article
Multiple Articles
Single Comment
Multiple Comments
List of Tags
Errors and Status Codes
If a request fails any validations, expect a 422 and errors in the following format:
Other status codes:
401 for Unauthorized requests, when a request requires authentication but it isn't provided
403 for Forbidden requests, when a request may be valid but the user doesn't have permissions to perform the action
404 for Not found requests, when a resource can't be found to fulfill the request
Endpoints:
Authentication:
POST /api/users/login
Example request body:
No authentication required, returns a User
Required fields: email
, password
Registration:
POST /api/users
Example request body:
No authentication required, returns a User
Required fields: email
, username
, password
Get Current User
GET /api/user
Authentication required, returns a User that's the current user
Update User
PUT /api/user
Example request body:
Authentication required, returns the User
Accepted fields: email
, username
, password
, image
, bio
Get Profile
GET /api/profiles/:username
Authentication optional, returns a Profile
Follow user
POST /api/profiles/:username/follow
Authentication required, returns a Profile
No additional parameters required
Unfollow user
DELETE /api/profiles/:username/follow
Authentication required, returns a Profile
No additional parameters required
List Articles
GET /api/articles
Returns most recent articles globally by default, provide tag
, author
or favorited
query parameter to filter results
Query Parameters:
Filter by tag:
?tag=AngularJS
Filter by author:
?author=jake
Favorited by user:
?favorited=jake
Limit number of articles (default is 20):
?limit=20
Offset/skip number of articles (default is 0):
?offset=0
Authentication optional, will return multiple articles, ordered by most recent first
Feed Articles
GET /api/articles/feed
Can also take limit
and offset
query parameters like List Articles
Authentication required, will return multiple articles created by followed users, ordered by most recent first.
Get Article
GET /api/articles/:slug
No authentication required, will return single article
Create Article
POST /api/articles
Example request body:
Authentication required, will return an Article
Required fields: title
, description
, body
Optional fields: tagList
as an array of Strings
Update Article
PUT /api/articles/:slug
Example request body:
Authentication required, returns the updated Article
Optional fields: title
, description
, body
The slug
also gets updated when the title
is changed
Delete Article
DELETE /api/articles/:slug
Authentication required
Add Comments to an Article
POST /api/articles/:slug/comments
Example request body:
Authentication required, returns the created Comment
Required field: body
Get Comments from an Article
GET /api/articles/:slug/comments
Authentication optional, returns multiple comments
Delete Comment
DELETE /api/articles/:slug/comments/:id
Authentication required
Favorite Article
POST /api/articles/:slug/favorite
Authentication required, returns the Article
No additional parameters required
Unfavorite Article
DELETE /api/articles/:slug/favorite
Authentication required, returns the Article
No additional parameters required
Get Tags
GET /api/tags
No authentication required, returns a List of Tags
Last updated