realworld-api

# 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 <http://www.apache.org/licenses/LICENSE-2.0> 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.