https://github.com/nickpeihl/realworld-api
RealWorld library for open API calls using JavaScript
https://github.com/nickpeihl/realworld-api
api-client realworld
Last synced: 7 months ago
JSON representation
RealWorld library for open API calls using JavaScript
- Host: GitHub
- URL: https://github.com/nickpeihl/realworld-api
- Owner: nickpeihl
- Created: 2017-09-26T22:16:59.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2017-10-16T23:09:38.000Z (almost 8 years ago)
- Last Synced: 2025-02-18T06:16:05.107Z (8 months ago)
- Topics: api-client, realworld
- Language: JavaScript
- Size: 124 KB
- Stars: 2
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# realworld-api
RealWorld library for open API calls using JavaScript
## about
[RealWorld](https://realworld.io/) is a fullstack Medium clone that can be written using many different web frameworks. It was developed as a way to show how to accomplish the same website using different backend and frontend technologies.
I created this module as a simple way to interact with the [RealWorld API Specification](https://github.com/gothinkster/realworld/tree/master/api#realworld-api-spec) which could be easily dropped in to any frontend technology stack.
Each public function is well-documented in the code using [JSDoc](http://usejsdoc.org) and the documentation can be automatically generated using [documentation.js](http://documentation.js.org/).
Unit tests are written to be isolated and idempotent. Addtionally, you do not have to be connected to the internet in order to run the tests. The tests run on an ephemeral local Node.js HTTP server and ensure the API requests are correct.
realworld-api mostly follows the logic of the [Tiny Guide to Non Fancy Node](https://github.com/yoshuawuyts/tiny-guide-to-non-fancy-node), however it makes use of template literals from ES6. If you are bundling realworld-api for use in an older browser that [doesn't support template literals](http://caniuse.com/#feat=template-literals), you may want to compile your code using [Babel](https://babeljs.io/) or use a browserify transform such as [ES2020](https://github.com/yoshuawuyts/es2020).
## install
```shell
npm install realworld-api
```
## usage
```javascript
var RealWorld = require('realworld-api')
var client = new RealWorld()
client.getArticles(function (err, res, data) {
if (err) throw err
console.log(data)
})
```
## api
### RealWorld
- **See: [RealWorld API Spec](https://github.com/gothinkster/realworld/tree/master/api#realworld-api-spec)**
Realworld library for open API calls using JavaScript
**Parameters**
- `opts` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** options for configuring API
- `opts.token` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** authentication token from RealWorld (optional, default `null`)
- `opts.apiRoot` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** the url
to Realworld API (optional, default `https://conduit.productionready.io/api`)
**Examples**
```javascript
var client = new RealWorld()
```
```javascript
var client = new RealWorld({
apiRoot: 'http://localhost:8000/api',
token: 'my-secret-authentication-token'
})
```
#### login
Log in to the RealWorld API
If successful, the `data` result will be type {User}
**Parameters**
- `opts` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `opts.email` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** email address of user
- `opts.password` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** password of user
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.login(
{
email: 'mike@example.com',
password: 'secret'
},
handleResponse
)
```
#### register
Register a new user with the RealWorld API
**Parameters**
- `opts` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `opts.username` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** username of registering user
- `opts.email` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** email address of registering user
- `opts.password` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** password of registering user
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.register(
{
email: 'rick@example.com',
password: 'shhhh',
username: 'rick'
},
handleResponse
)
```
#### getUser
Get the logged in user
**Parameters**
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.getUser(handleResponse)
```
#### updateUser
Update the logged in user info
**Parameters**
- `opts` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `opts.email` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** email address of user (optional, default `null`)
- `opts.username` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** username of user (optional, default `null`)
- `opts.bio` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** biography of user (optional, default `null`)
- `opts.password` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** password of user (optional, default `null`)
- `opts.image` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** url of user image (optional, default `null`)
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.updateUser(
{
email: 'stacy@example.com',
password: 'hush',
username: 'stace',
bio: 'riot grrl'
},
handleResponse
)
```
#### getProfile
Get profile of a user
**Parameters**
- `username` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** username of profile to retrieve
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.getProfile('rick', handleResponse)
```
#### followUser
Follow a user (authentication required)
**Parameters**
- `username` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** username to follow
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.followUser('rick', handleResponse)
```
#### unFollowUser
Unfollow a user (authentication required)
**Parameters**
- `username` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** username to unfollow
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.unFollowUser('rick', handleResponse)
```
#### listAllArticles
Request a list of 20 articles sorted by most recent in descending order
**Parameters**
- `page` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** page specify which page of articles to show (optional, default `0`)
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.listAllArticles(handleResponse)
```
```javascript
client.listAllArticles(2, handleResponse)
```
#### listArticlesByTag
Request a list of 10 articles filtered by a tag and sorted by most recent
in descending order
**Parameters**
- `tag` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** tag name to filter by
- `page` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** specify which page of articles to show (optional, default `0`)
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.listArticlesByTag('JavaScript', handleResponse)
```
```javascript
client.listArticlesByTag('JavaScript', 2, handleResponse)
```
#### listArticlesByAuthor
Request a list of five articles filtered by author and sorted by most recent
in descending order
**Parameters**
- `author` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** username of author to filter by
- `page` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** specify which page of articles to show (optional, default `0`)
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.listArticlesByAuthor('rick', handleResponse)
```
```javascript
client.listArticlesByAuthor('rick', 2, handleResponse)
```
#### listArticlesByAuthorFavorites
Request a list of 20 articles filtered by author favorites and sorted by most
recent in descending order
**Parameters**
- `author` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** username of author to filter favorite articles by
- `page` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** specify which page of articles to show (optional, default `0`)
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.listArticlesByAuthorFavorites('rick', handleResponse)
```
```javascript
client.listArticlesByAuthorFavorites('rick', 1, handleResponse)
```
#### feedArticles
Request a list of ten articles from the currently logged in users feed sorted
by most recent in descending order (authentication required)
**Parameters**
- `page` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** specify which page of articles to show (optional, default `0`)
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.feedArticles(handleResponse)
```
```javascript
client.feedArticles(2, handleResponse)
```
#### getArticle
Request contents from a single article with the specified slug
**Parameters**
- `slug` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** shortname (slug) of article
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.getArticle('angular-app-dev-e33mn9', handleResponse)
```
#### createArticle
Create a new article (authentication required)
**Parameters**
- `opts` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `opts.title` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** title of article
- `opts.description` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** short description of article
- `opts.body` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** content of article
- `opts.tagList` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** array of tags to add to article (optional, default `null`)
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.createArticle(
{
title: 'My awesome article',
description: 'beep boop',
body: 'wham bam thank you ma\'am',
tagList: ['awesomeness', 'robots']
},
handleResponse
)
```
#### updateArticle
Update an existing article with given slug and options (authentication
required)
**Parameters**
- `slug` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** shortname (slug) of article to update
- `opts` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `opts.title` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** title of article (optional, default `null`)
- `opts.description` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** short description of article (optional, default `null`)
- `opts.body` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** content of article (optional, default `null`)
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.updateArticle('my-awesome-article-ew9439', {
title: 'my awesome gender neutral article',
description: 'boop beep',
body: 'wham bam thank you friend'
})
```
#### deleteArticle
Delete an existing article with the given slug (authentication required)
**Parameters**
- `slug` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** shortname (slug) of article to delete
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.deleteArticle('my-awesome-article-ew9439', handleResponse)
```
#### addComment
Add a comment to an article with the given slug (authentication required)
**Parameters**
- `slug` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** shortname (slug) of article to add comment to
- `opts` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `opts.body` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** content of comment
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.addComment(
'my-awesome-article-ew9439',
{
body: 'this is a good article'
},
handleResponse
)
```
#### getComments
Get comments from an article
**Parameters**
- `slug` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** shortname (slug) of article from which to retrieve
comments
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.getComments('angular-app-dev-e33mn9', handleResponse)
```
#### deleteComment
Delete comment from an article (authentication required)
**Parameters**
- `slug` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** shortname (slug) of article
- `commentId` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** unique id of comment to delete
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.deleteComment('angular-app-dev-e33mn9', 'e11dfeg', handleResponse)
```
#### favoriteArticle
Favorite an article (authentication required)
**Parameters**
- `slug` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** shortname (slug) of article to favorite
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.favoriteArticle('my-awesome-article-ew9439', handleResponse)
```
#### unFavoriteArticle
Unfavorite an article (authentication required)
**Parameters**
- `slug` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** shortname (slug) of article to unfavorite
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.unFavoriteArticle('my-awesome-article-ew9439', handleResponse)
```
#### getTags
Get a list of tags
**Parameters**
- `cb` **[RealWorld~requestCallback](#realworldrequestcallback)** Callback function
**Examples**
```javascript
client.getTags(handleResponse)
```
#### setToken
Set the authentication token
**Parameters**
- `_token` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** authentication token to set
**Examples**
```javascript
client.setToken('my-secret-authentication-token')
```
### RealWorld~requestCallback
This callback is displayed as part of the RealWorld class. The error should
be null if the method was able to run. HTTP and API errors are not caught as
errors so that you can catch them yourself. For example, a response code 500
may return `(null, { res.statusCode: 500, res.statusMessage: 'Internal Server Error' }, null)`.
API errors are returned with a 422 status code. Errors are included as JSON
in the `data` result and are in the form of
`{
"errors":{
"body": [
"can't be empty"
]
}
}`
where `body` may be any parameter such as `password`, `email`, etc.
Successful API requests will return JSON data as seen in the
[RealWorld API Spec](https://github.com/gothinkster/realworld/tree/master/api#realworld-api-spec)
Type: [Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)
**Parameters**
- `err` **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** error if method was unable to run
- `res` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** response object from server
- `data` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** data result from the server as JSON
**Examples**
```javascript
function handleResponse (err, res, data) {
if (err) return console.error(err)
if (res.statusCode === 422 && data.errors) {
Object.keys(data.errors).forEach(function (err) {
var values = data.errors[err]
values.forEach(function (v) {
console.error(`${err} ${v}`)
})
})
return
}
if (res.statusCode !== 200) {
return console.log(`${res.statusCode}: ${res.statusMessage}`)
}
return console.log(data)
}
```
## license
Copyright 2017 Nick Peihl
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.