FavQs API v2

Access our API at:

https://favqs.com/api/

For example, get the Quote of the Day:

https://favqs.com/api/qotd

All data is sent and received as JSON.

Headers

All data is sent and received as JSON.

Content-Type: application/json

This must be set in the request headers when the request body contains content.

There are three HTTP status codes that you need to check for: 200, 404, and 500.

Success

A successful request returns a 200 response and no error_code.

Validation Errors

A request containing validation errors will return a 200 response (breaking from 4xx convention) as well as an error_code and message containing the reason (in English) for the validation error. A full list of error codes is available in the last section of this page if you would like to provide translations within your app.

Summary

To recap, check for a 200 to see if the server received and understood your request. Then check for the presence of an error_code to make sure there were no validation errors on your request. If there were, a message will be present and can be shown to the user.

An app token is required to access our API (except for the Quote of the Day).

For authorized API calls, pass your access token in via the header:

Authorization: Token token="YOUR_APP_TOKEN"

For example,

$ curl -H 'Authorization: Token token="YOUR_APP_TOKEN"'

Note: This format will not work:

Authorization: "YOUR_APP_TOKEN"

For calls that require a user session, pass the user token in via the header:

User-Token: "USER_SESSION_TOKEN"

The double quotes are optional.

You can specify the version of the API in the header of each request.

$ curl -H 'Accept: application/vnd.favqs.v2+json;'

Note: The API will default to the latest version if no version is specified.

It is a best practice to include the version of the API in each request, as the default version could change and break your app.

Previous Versions

Prior versions of the API include Version 1.

All responses include an ETag (Entity Tag) in the header. The ETag identifies the specific version of a returned resource. Use this value to check for changes to a resource by repeating the request and passing the ETag value in the If-None-Match header. If the resource has not changed, a 304 Not Modified status will be returned with an empty body. If the resource has changed, the request will return the resource.

Response Header

HTTP/1.1 200 OK 
...
Etag: "558f0b9bea2e6910b1f93de7f4c0d47c"

Request

$ curl -I -H 'If-None-Match: "558f0b9bea2e6910b1f93de7f4c0d47c"'
HTTP/1.1 304 Not Modified

Access to the API is rate limited. Each session is allowed 30 requests in a 20 second interval.

The remaining number of requests is returned in the HTTP header 'Rate-Limit-Remaining'.

Response Header

HTTP/1.1 200 OK 
...
Rate-Limit-Remaining: 24

Session

A user can only have one session per app token. If you have more than one app, please request another app token.

To create a session for the user, inside your application:

Request

POST /api/session

Request Body

Note: A user can login with their username or email address.

{ 
  "user": {
    "login": "login_or_email_here",
    "password": "user_password_here"
  }
}

Response Body

{ 
  "User-Token": "i4dwXAUNfSUEaTP90K5RWOWLap5cvc9mtjfpvA+c0uufP5GYnpYZUO4k5pTEpwsJHVHNhY5lbLn0cDRpiwsOKA==",
  "login": "user_login",
  "email": "user_email"
}

The "User-Token" should be added to the header for requests that require a user session.

Errors

An invalid login or password will return an error:

{ 
  "error_code": 21,
  "message": "Invalid login or password."
}

An account that has been deactivated will return an error:

{ 
  "error_code": 22,
  "message": "Login is not active. Contact [email protected]."
}

A request with missing data will return an error:

{ 
  "error_code": 23,
  "message": "User login or password is missing."
}

To destroy a user session (logout):

Request

DELETE /api/session

Response Body

{ 
  "message": "User logged out."
}

Error

If the user revokes account access to your app from their FavQs.com account page, you will see:

{ 
  "error_code": 20,
  "message": "No user session found."
}

Users

To create a new user:

Request

POST /api/users

Request Body

{ 
  "user": {
    "login": "user_login_here",
    "email": "user_email_here",
    "password": "user_password_here"
  }
}

Validations

Login	Can only contain letters (a-z), numbers (0-9) and the underscore (_) Length must be between 1 and 20 characters
Email	Must be a valid email address
Password	Length must be between 5 and 120 characters

Response Body

Successful creation of a user will return a session token for that user.

{ 
  "User-Token": "i4dwXAUNfSUEaTP90K5RWOWLap5cvc9mtjfpvA+c0uufP5GYnpYZUO4k5pTEpwsJHVHNhY5lbLn0cDRpiwsOKA==",
  "login": "user_login"
}

The "User-Token" should be added to the header for requests that require a user session.

Errors

If a user session already exists, you will get an error:

{ 
  "error_code": 31,
  "message": "User session present."
}

If any of the fields contain validation errors, message will contain a list of validation errors separated by a semi-colon.

{
  "error_code": 32,
  "message": "Email is not a valid email; Password is too short (minimum is 5 characters)"
}

To get a user:

Request

GET /api/users/:login

Response

A user session may query any user.

{
  "login": "gose",
  "pic_url": "https://pbs.twimg.com/profile_images/2160924471/Screen_Shot_2012-04-23_at_9.23.44_PM_.png",
  "public_favorites_count": 520,
  "followers": 12,
  "following": 23,
  "pro": true
}

Response

Note: User session required

If you request the user of the current user session, you will also get "account_details".

{
  "login": "gose",
  "pic_url": "https://pbs.twimg.com/profile_images/2160924471/Screen_Shot_2012-04-23_at_9.23.44_PM_.png",
  "public_favorites_count": 520,
  "followers": 12,
  "following": 23,
  "pro": true,
  "account_details": {
    "email": "[email protected]",
    "private_favorites_count": 22,
    "pro_expiration": "2015-03-13T07:19:06.133-05:00"
  }
}

If the user is Pro, you will also get anpro_expiration .

Note: User session required

To update a user:

Request

PUT /api/users/:login

Request Body

All fields are optional.

{ 
  "user": {
    "login": "user_login_here",
    "email": "user_email_here",
    "password": "user_password_here",
    "twitter_username": "twitter_username_here",
    "facebook_username": "facebook_username_here",
    "pic": "twitter",
    "profanity_filter": false
  }
}

Validations

Additional validations are listed under 'Create User'.

Pic	Either `["twitter", "facebook", "gravater", ""]`
Profanity Filter	Must be either `[true, false]`. True means it's enabled (default).

Response Body

{ 
  "message": "User successfully updated."
}

Profile Pics

Setting a user's profile picture involves:

Setting "twitter_username", "facebook_username", or relying on the user's email having a Gravatar.
Setting "pic" to either ["twitter", "facebook", "gravater", ""]

Request Body

For example, to set user gose's pic to their Twitter handle 'sgose':

{ 
  "user": {
    "twitter_username": "sgose",
    "pic": "twitter"
  }
}

Errors

If there is a validation error, one or more validation errors will be returned:

{
  "error_code": 32,
  "message": {
    "login": [
      "has already been taken"
    ],
    "email": [
      "is not a valid email"
    ]
  }
}

To request a password reset.

Request

POST /api/users/forgot_password

Request Body

{ 
  "user": {
    "email": "user_email_here"
  }
}

Response Body

{ 
  "message": "A reset link has been emailed."
}

Errors

If the user login or email is not found, a 404 will be returned.

{ 
  "error_code": 30,
  "message": "User not found."
}

To reset a password:

Request

POST /api/users/reset_password

Request Body

{ 
  "user": {
    "email": "user_email_here",
    "reset_password_token": "user_reset_password_token_here"
  }
}

Response Body

{ 
  "message": "Password successfully updated. Please login."
}

Errors

If the password reset token is invalid:

{ 
  "error_code": 33,
  "message": "Invalid password reset token."
}

To purchase a one year FavQs Pro subscription, open the following URL in a web view:

GET /users/:login/pro

Typeahead

This resource provides a list of the public Authors, Tags, and Users in FavQs.

With this data, typeahead can be performed locally giving the user a fast response.

Request

GET /api/typeahead

Response

{
  "authors": [
    {
      "count": 118,
      "permalink": "mark-twain",
      "name": "Mark Twain"
    },
    ...
  ],
  "tags": [
    {
      "count": 44,
      "permalink": "funny",
      "name": "funny"
    },
    ...
  ],
  "users": [
    {
      "count": 432,
      "permalink": "gose",
      "name": "gose"
    },
    ...
  ]
}

Quotes

Get the Quote of the Day.

Request

GET /api/qotd

Example

$ curl https://favqs.com/api/qotd

Response

{
  "qotd_date": "2014-07-04T03:00:00.000-05:00",
  "quote": {
    "id": 17025,
    "favorites_count": 0,
    "dialogue": false,
    "favorite": false,
    "tags": [
      "equality",
      "men"
    ],
    "url": "http://localhost:3000/quotes/abraham-lincoln/17025-fourscore-and-",
    "upvotes_count": 1,
    "downvotes_count": 0,
    "author": "Abraham Lincoln",
    "author_permalink": "abraham-lincoln",
    "body": "Fourscore and seven years ago our fathers brought forth on this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal."
  }
}

A list of quotes, paged 25 at a time.

Request

GET /api/quotes

Response

{
  "page": 1,
  "last_page": false,
  "quotes": [
    {
      "tags": [
        "linux",
        "programming",
        "code",
        "finnish-american"
      ],
      "favorite": false,
      "author_permalink": "linus-torvalds",
      "body": "Talk is cheap. Show me the code.",
      "id": 253,
      "favorites_count": 1,
      "upvotes_count": 0,
      "downvotes_count": 0,
      "dialogue": false,
      "author": "Linus Torvalds",
      "url": "https://favqs.com/quotes/linus-torvalds/253-talk-is-cheap-s-"
    },
    ...
  ]
}

Optional URL Parameters

The list of quotes can be refined via these filters.

Parameter	Description
filter	Type lookup or keyword search
type	`['author', 'tag', 'user']`
private	Get private quotes for the pro user session (e.g., private=true)
hidden	Get hidden quotes for the user session (e.g., hidden=true)
page	Page number (25 quotes per page)

Examples

Get a random list of quotes:

GET https://favqs.com/api/quotes/

Search for quotes containing the word "funny":

GET https://favqs.com/api/quotes/?filter=funny

Get quotes that are tagged with "funny":

GET https://favqs.com/api/quotes/?filter=funny&type=tag

Get quotes by Mark Twain:

GET https://favqs.com/api/quotes/?filter=Mark+Twain&type=author

Get the public quotes favorited by user 'gose':

GET https://favqs.com/api/quotes/?filter=gose&type=user

Get the private quotes of the current user (pro session required):

GET https://favqs.com/api/quotes/?private=1

Search for private quotes of the current user session that contain the words "little book":

GET https://favqs.com/api/quotes/?filter=little+book&private=1

Get quotes hidden by the user:

GET https://favqs.com/api/quotes/?hidden=1

Request

GET /api/quotes/:quote_id

Response Body

{
  "id": 4,
  "author": "Albert Einstein",
  "body": "Make everything as simple as possible, but not simpler.",
  ...
}

To mark a quote as a user's favorite:

Request

PUT /api/quotes/:quote_id/fav

Response Body

{
  "id": 4,
  "author": "Albert Einstein",
  "body": "Make everything as simple as possible, but not simpler.",
  ...
  "user_details": {
    "favorite": true,
    ...
  }
}

Errors

{ 
  "error_code": 40,
  "message": "Quote not found."
}

Request

To unmark a quote as a user's favorite:

PUT /api/quotes/:quote_id/unfav

Response Body

{
  "id": 4,
  "author": "Albert Einstein",
  "body": "Make everything as simple as possible, but not simpler.",
  ...
  "user_details": {
    "favorite": false,
    ...
  }
}

Errors

{ 
  "error_code": 41,
  "message": "Private quotes cannot be unfav'd."
}

Users can vote a quote up or down to influence that quotes popularity.

Vote a quote up:

Request

PUT /api/quotes/:quote_id/upvote

Response Body

{
  "id": 4,
  "author": "Albert Einstein",
  "body": "Make everything as simple as possible, but not simpler.",
  ...
  "user_details": {
    "upvote": true,
    "downvote": false,
    ...
  }
}

Vote a quote down:

Request

PUT /api/quotes/:quote_id/downvote

Response Body

{
  "id": 4,
  "author": "Albert Einstein",
  "body": "Make everything as simple as possible, but not simpler.",
  ...
  "user_details": {
    "upvote": false,
    "downvote": true,
    ...
  }
}

To clear the vote on a quote:

Request

PUT /api/quotes/:quote_id/clearvote

Response Body

{
  "id": 4,
  "author": "Albert Einstein",
  "body": "Make everything as simple as possible, but not simpler.",
  ...
  "user_details": {
    "upvote": false,
    "downvote": false,
    ...
  }
}

To add Personal Tags to a quote:

Request

PUT /api/quotes/:quote_id/tag

The list of tags sent must include all of the user's personal tags for that quote.

Request Body

{
  "personal_tags": [
    "simplicity",
    "minimalism"
  ]
}

If a tag is missing from the list, that personal tag will be removed from the quote.

Response Body

{
  "id": 4,
  "author": "Albert Einstein",
  "body": "Make everything as simple as possible, but not simpler.",
  ...
  "user_details": {
    "personal_tags": [
      "simplicity",
      "minimalism"
    ]
    ...
  }
}

To hide a quote:

Request

PUT /api/quotes/:quote_id/hide

Response Body

{
  "id": 4,
  "author": "Albert Einstein",
  "body": "Make everything as simple as possible, but not simpler.",
  ...
  "user_details": {
    "hidden": true,
    ...
  }
}

To unhide a quote:

Request

PUT /api/quotes/:quote_id/unhide

Response Body

{
  "id": 4,
  "author": "Albert Einstein",
  "body": "Make everything as simple as possible, but not simpler.",
  ...
  "user_details": {
    "hidden": false,
    ...
  }
}

Quotes added by Pro users are private initially and can be edited.

Quotes added by non-Pro users are public and cannot be edited.

To add a quote:

Request

POST /api/quotes

Request Body

{
  "quote": {
    "author": "Mark Twain",
    "body": "Never let your schooling interfere with your education."
  }
}

To add a dialogue:

Request

POST /api/quotes

Request Body

{
  "quote": {
    "lines": [
      {
        "author": "State Trooper",
        "body": "Pullover!"
      },
      {
        "author": "Harry Dunne",
        "body": "No, it's a cardigan but thanks for noticing."
      },
      {
        "author": "Lloyd Christmas",
        "body": "Yeah, killer boots man!"
      }
    ],
    "source": "Dumb & Dumber, 1994. Film",
    "context": "While being pulled over by a State Trooper on a motorcycle.",
    "tags": "funny, movie, dumb and dumber, police"
  }
}

Response Body

The response is the same as Get Quote.

{
  "id": 123,
  "author": "Mark Twain",
  "body": "Never let your schooling interfere with your education."
  ...
}

Updating a quote or dialogue requires the same request format as adding a quote.

Request

PUT /api/quotes/:quote_id

Response

The response is the same as Get Quote.

To delete a quote:

Request

DELETE /api/quotes/:quote_id

Response Header

HTTP/1.1 200 OK

To make a quote public:

Request

PUT /api/quotes/:quote_id/publicize

Once a quote is public, it cannot be edited and others will be able to see, fav it, etc.

Response Body

{
  "id": 4,
  "author": "Albert Einstein",
  "body": "Make everything as simple as possible, but not simpler.",
  "private": false
  ...

Activity

Get the activity of a user, tag, or author, sorted by recency.

Request

GET /api/activities/

If a user session is present and no parameters are given, the activites for that user will be returned.

URL Parameters

Parameter	Description
filter	Type lookup
type	`['author', 'tag', 'user']`
page	Page number (25 activities per page)

Response Body

{
  "activities": [
    {
      "activity_id": 427,
      "owner_type": "User",
      "owner_id": "gose",
      "owner_value": "gose",
      "action": "favorited",
      "trackable_id": 61003,
      "trackable_type": "Quote",
      "trackable_value": "Pleasure in the job puts perfection in the work. - Aristotle",
      "message": "User gose favorited Quote \"Pleasure in the job puts perfection in the work.\" - Aristotle" 
    },
    {
      "activity_id": 426,
      "owner_type": "User",
      "owner_id": "gose",
      "owner_value": "gose",
      "action": "followed",
      "trackable_id": "chicago",
      "trackable_type": "Tag",
      "trackable_value": "chicago",
      "message": "User gose followed Tag chicago"
    },
    ...
  ]
}

Examples

Get the activities of user 'gose':

GET https://favqs.com/api/activities/?type=user&filter=gose

Get the activities of author Mark Twain:

GET https://favqs.com/api/activities/?type=author&filter=Mark+Twain

Get the activities of tag "funny":

GET https://favqs.com/api/activities/?type=tag&filter=funny

To delete an activity entry:

Request

DELETE /api/activities/:activity_id

Successful requests return a 200 OK and empty body.

To follow a user, tag, or author:

Request

PUT /api/activities/follow/

To unfollow a user, tag, or author:

Request

PUT /api/activities/unfollow/

Required URL Parameters

Parameter	Description
filter	Type lookup
type	`['author', 'tag', 'user']`

Successful requests return a 200 OK.

To get the followers for a user, tag, or author:

Request

GET /api/activities/followers/

Required URL Parameters

Parameter	Description
filter	Type lookup
type	`['author', 'tag', 'user']`

For example, get users who follow user 'gose':

GET https://favqs.com/api/activities/followers?type=user&filter=gose

Response Body

{
  "page": 1,
  "last_page": true,
  "users": [
    "david",
    "michael",
    "john"
  ]
}

Get users who follow tag 'funny':

GET https://favqs.com/api/activities/followers?type=tag&filter=funny

Get users who follow author 'Mark Twain':

GET https://favqs.com/api/activities/followers?type=author&filter=mark-twain

To get a list of users, tags, and authors a user is following:

Request

GET /api/activities/following/

Only users can follow authors, tags, and other users.

Response Body

{
  "page": 1,
  "last_page": true,
  "following": [
    {
      "following_type": "Author",
      "following_id": "mark-twain",
      "following_value": "Mark Twain"
    },
    {
      "following_type": "Tag",
      "following_id": "society",
      "following_value": "society"
    },
    {
      "following_type": "User",
      "following_id": "david",
      "following_value": "david"
    }
  ]
}

Optional URL Parameters

Parameter	Description
user	Username

To see who is following the current user:

GET https://favqs.com/api/activities/following

To see who is following user 'gose':

GET https://favqs.com/api/activities/following/?user=gose

Errors

Successful requests return a 200 OK response, and no error_code.

If your request returns a 200 OK and an error_code, the request could not be completed.

Response Body

{ 
  "error_code": 21,
  "message": "Invalid login or password."
}

An additional message will indicate the reason, but you can present your own message based off the error_code.

Error Codes

10	Invalid request.
11	Permission denied.
20	User session not found.
21	Invalid login or password.
22	Login is not active. Contact [email protected].
23	User login or password is missing.
24	Pro user required
30	User not found.
31	User session already present.
32	A list of 'user' validation errors.
33	Invalid password reset token.
40	Quote not found.
41	Private quotes cannot be unfav'd.
42	Could not create quote.
50	Author not found.
60	Tag not found.
70	Activity not found.

Additional error scenarios include non-200 codes in the response header.

404	HTTP/1.1 404 Not Found
500	HTTP/1.1 500 Internal Server Error

FavQs

FavQs API v2

Headers

Content Type

Status Codes

Success

Validation Errors

Summary

Authorization

User Session

Versions

Previous Versions

Caching

Response Header

Request

Rate Limiting

Response Header

Session

Create Session

Request

Request Body

Response Body

Errors

Destroy Session

Request

Response Body

Error

Users

Create User

Request

Request Body

Validations

Response Body

Errors

Get User

Request

Response

Response

Update User

Request

Request Body

Validations

Response Body

Profile Pics

Request Body

Errors

Forgot Password

Request

Request Body

Response Body

Errors

Reset Password

Request

Request Body

Response Body

Errors

Fav Qs Pro

Typeahead

Filters

Request

Response

Quotes

Quote of the Day (no token required)

Request

Example

Response

List Quotes

Request

Response

Optional URL Parameters

Examples

Get Quote

Request

Response Body

Fav Quote(user session required)

Request

Response Body

Errors

Request

Response Body