Forrst API v2 Documentation

Last updated November 16, 2011 · Support

Note: The Forrst API is currently under development. While we'll do our best to ensure things don't break, for the time being please consider this to be beta-quality. Also, the rate limit of 150 is soft during testing, so don't worry about going over right now.

Overview

The Forrst API allows developers to interact with posts, comments, users, and so forth via an easy to use JSON API. Right now, the API is read-only, but will be expanded to provide full read and write support, as well as a Sign in with Forrst feature powered by OAuth2.

Endpoints

All calls should be made using https://forrst.com/api/v2/ as the endpoint (e.g. calling posts/all would be https://forrst.com/api/v2/posts/all). Making calls over SSL is required, and calls over regular http may be disabled at some point in the future.

Authentication & Access Tokens

We support token-based authentication. These tokens may be passed via a GET parameter named access_token and do not expire. If authentication is unsuccessful you will receive an error response. Most authenticated calls return additional data, scoped to the requesting user.

If a method is listed as authentication optional, authenticating is not required, but doing so will return additional data that the authenticating user would be able to access if logged-in.

Responses

We've made every attempt to ensure that we return sane HTTP status codes for your requests. Additionally, error responses generally contain useful information about why the call failed.

Also, there are a few special values returned with each response: in - response time in seconds, env - the environment (will always be prod), stat - the status; will be ok or fail, authed - was the request an authenticated one?, and finally, authed_as - who is the authenticating user? (false when unauthenticated).

We also support JSONP responses. Simply pass an additional query string parameter named callback. Callbacks must only contain _, a-z, A-Z, and 0-9, and are sanitized on our end.

For endpoints that return post data, an additional boolean attribute named user_likes is included for each record. It indicates whether the authenticating user likes that content. Note that users can never like their own content.

Formatting

Comments and posts are formatted using our formatting system, which includes autolinking and Markdown formatting. Comments' body fields are always returned formatted. Posts have extra fields prefixed with "formatted_" which contain formatted versions of their raw counterparts (e.g. content vs. formatted_content).

Rate Limiting

All API calls (with the exception of stats) are rated limited at 150 calls per hour. In the future, we will offer whitelisting by request. When making unauthenticated calls, each request counts against the total made by the calling IP address; when authenticating, calls count against the authenticated user's limit. You may request rate limiting stats at api/v2/stats (it won't count against your total). Your limit resets each hour.

Being a good citizen

When making API requests, we encourage you to use a unique User-Agent to identify your app. Caching and other best practices are encouraged. We reserve the right to suspend access to clients using default user agent headers or making prolific requests.

Also, please respect post and user visibility when making authenticated calls.

Apps & Branding

We can't wait to see what you build with the API, but please don't use Forrst in the name or otherwise use our branding (logo, images, layout, etc.) without permission. You're developers and designers; be creative!

OAuth

We plan to support "Sign in with Forrst"-type functionality using OAuth2 sometime in the near future. Stay tuned for that. (We actually already use this internally for Forrst.me)

Commercial Use

Please contact us if you intend to use the API for commercial purposes.

Legal

We reserve the right to suspend access at any time for any reason if we feel it is warranted (e.g. abuse). We also reserve the right to change anything here (API, docs, rules, etc.) at any time and for any reason. Play nice!

Methods

stats

Returns stats about your API usage. Note: does not count against your rate limit.

Type: Read
Method: GET
Must Authenticate? No

Sample Response: 
{
  "resp": {
    "rate_limit": 150,
    "calls_made": "31"
  },
  "stat": "ok",
  "in": 0.0465,
  "authed": false,
  "authed_as": false,
  "env": "dev"
}

notifications

Return notification items for the authenticating user. Most items have an associated redirect URL that will take the user to the appropriate post/comment/etc. and clear the associated notification. Construct the URLs using the view_url_format format (provided in the response), replacing ID with the ID of the desired notification. Also note that not every type of notification (currently for likes, comments [replies, subscription-based, on your post], mentions, jobs, and follows) will have the same fields present for data.

Type: Read
Method: GET
Must Authenticate? Yes
Params:
  • grouped: [optional] Boolean indicating whether to return items logically grouped by type

Sample Response: 
{
  "resp":{
    "items":{
      "like":{
        "7711438e4370b4e705a792532a1c63663hwcQn21pNYV":{
          "id":"7711438e4370b4e705a792532a1c63663hwcQn21pNYV",
          "timestamp":1315511539,
          "behavior":"like",
          "for_user_id":21,
          "object_type":"Post",
          "object_id":79097,
          "data":{
            "actor":"kyle",
            "actor_url":"\/people\/kyle",
            "object_url":"\/posts\/Announcing_Attachments-9Vc",
            "post_type":"question",
            "post_title":"Announcing Attachments.",
            "photo":"https:\/\/forrst-development.s3.amazonaws.com\/users\/photos\/1\/thumb.png?1302056245"
          }
        }
      }
    },
    "view_url_format":"https:\/\/forrst.com\/feed\/view\/:id"
  },
  "stat":"ok",
  "in":0.2789,
  "authed":true,
  "authed_as":[
    21,
    "forrst"
  ],
  "env":"dev"
}

users/auth

User authentication. Provide an email/username and password and get an access token back

Type: Read
Method: POST
Must Authenticate? Yes
Params:
  • email_or_username: Email/Username
  • password: Password

Sample Response: 
{
  "resp": {
    "token": "your-token-will-be-here",
    "user_id": 123
  },
  "stat": "ok",
  "in": 0.494,
  "authed": false,
  "authed_as": false,
  "env": "dev"
}

users/info

Returns user info

Type: Read
Method: GET
Must Authenticate? Optional
Params:
  • id: User ID
  • username: Username

Sample Response: 
{
  "resp": {
    "id": 1,
    "username": "kyle",
    "name": "Kyle Bragger",
    "url": "http://forrst.com/people/kyle",
    "posts": "390",
    "comments": "3613",
    "likes": "3500",
    "followers": "13628",
    "following": "13327",
    "photos": {
      "xl_url": "http://forrst-production.s3.amazonaws.com/users/photos/1/xl.png?1303409882",
      "large_url": "http://forrst-production.s3.amazonaws.com/users/photos/1/large.png?1303409882",
      "medium_url": "http://forrst-production.s3.amazonaws.com/users/photos/1/medium.png?1303409882",
      "small_url": "http://forrst-production.s3.amazonaws.com/users/photos/1/small.png?1303409882",
      "thumb_url": "http://forrst-production.s3.amazonaws.com/users/photos/1/thumb.png?1303409882"
    },
    "bio": "<p>my bio</p>\n",
    "is_a": "developer & designer",
    "homepage_url": "http://www.foo.com/",
    "twitter": "kylebragger",
    "in_directory": false,
    "tag_string": "php,scaling,startups,forrst"
  },
  "stat": "ok",
  "in": 2.8597,
  "authed": false,
  "authed_as": false,
  "env": "dev"
}

user/posts

Returns a user's posts

Type: Read
Method: GET
Must Authenticate? Optional
Params:
  • id: User ID
  • username: Username
  • type: [optional] Post type (code, snap, link, question)
  • limit: [optional, default = 10, max = 25] number of posts to return per page
  • after: [optional] if given, return posts with an ID lower than after

Sample Response: 
{
  "resp": {
    "posts": [
      {
        "id": 34738,
        "tiny_id": "5iO",
        "post_type": "snap",
        "post_url": "http://forrst.com/posts/Untitled-5iO",
        "created_at": "2010-10-23 18:13:02",
        "updated_at": "2010-11-07 07:50:01",
        "user": {
          ...snip...
        },
        "published": true,
        "public": true,
        "title": "Untitled",
        "url": "",
        "content": "",
        "description": "...",
        "formatted_description": "...",
        "like_count": "4",
        "comment_count": "6",
        "snaps": {
          "mega_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/34738/mega.png?1287857582",
          "keith_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/34738/keith.png?1287857582",
          "large_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/34738/large.png?1287857582",
          "medium_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/34738/medium.png?1287857582",
          "small_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/34738/small.png?1287857582",
          "thumb_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/34738/thumb.png?1287857582",
          "original_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/34738/original.png?1287857582"
        }
      },
      ...snip...
    ]
  },
  "stat": "ok",
  "in": 0.0774,
  "authed": false,
  "authed_as": false,
  "env": "dev"
}

posts/show

Return data about a single post. Note: For questions, content is the question. For code, content contains the code snippet. For code, snaps, and links, description is the post description; it is not used for questions.

Type: Read
Method: GET
Must Authenticate? Optional
Params:
  • id: Post ID
  • tiny_id: Post Tiny ID

Sample Response: 
{
  "resp": {
    "id": 45114,
    "tiny_id": "BMH",
    "post_type": "code",
    "post_url": "http://forrst.com/posts/Rails_3_Complex_Queries_with_Composed_Scopes-BMH",
    "created_at": "2010-12-15 09:28:17",
    "updated_at": "2010-12-15 09:28:33",
    "user": {
      ...snip...
    },
    "published": true,
    "public": true,
    "title": "Rails 3 Complex Queries with Composed Scopes",
    "url": "",
    "content": "...",
    "description": "...",
    "formatted_description": "...",
    "like_count": "1",
    "comment_count": "0",
    "tag_string": "rails, ruby, activerecord, activerelation",
    "tags": ["activerecord","activerelation","rails","ruby"]
  },
  "stat": "ok",
  "in": 0.0747,
  "authed": false,
  "authed_as": false,
  "env": "dev"
}

posts/all

Returns a list of all posts in reverse-chron order

Type: Read
Method: GET
Must Authenticate? Optional
Params:
  • after: [optional] if passed, only return posts posted after this ID

Sample Response: 
{
  "resp": {
    "posts": [
      {
        "id": 45146,
        "tiny_id": "BfC",
        "post_type": "snap",
        "post_url": "http://forrst.com/posts/test-BfC",
        "created_at": "2011-01-31 20:10:21",
        "updated_at": "2011-05-05 15:57:25",
        "user": {
          ...snip...
        },
        "published": true,
        "public": true,
        "title": "test",
        "url": "http://forrst.com",
        "content": "",
        "description": "test!",
        "formatted_content": "\n",
        "formatted_description": "
test!
\n",
        "like_count": "1",
        "comment_count": "0",
        "snaps": {
          "mega_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/mega.png?1296504621",
          "keith_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/keith.png?1296504621",
          "large_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/large.png?1296504621",
          "medium_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/medium.png?1296504621",
          "small_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/small.png?1296504621",
          "thumb_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/thumb.png?1296504621",
          "original_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/original.png?1296504621"
        }
      },
      ...snip...
    ],
    "page": 1
  },
  "stat": "ok",
  "in": 0.1557,
  "authed": false,
  "authed_as": false,
  "env": "dev"
}

posts/list

Returns a list of posts of a given type

Type: Read
Method: GET
Must Authenticate? Optional
Params:
  • post_type: Post type (code, snap, link, question)
  • sort: [optional, default = recent] Sort by recent, popular, best (staff picks)
  • page: [optional, default = 1] Page of results to return

Sample Response: 
{
  "resp": {
    "posts": [
      {
        "id": 45146,
        "tiny_id": "BfC",
        "post_type": "snap",
        "post_url": "http://forrst.com/posts/test-BfC",
        "created_at": "2011-01-31 20:10:21",
        "updated_at": "2011-05-05 15:57:25",
        "user": {
          ...snip...
        },
        "published": true,
        "public": true,
        "title": "test",
        "url": "http://forrst.com",
        "content": "",
        "description": "test!",
        "formatted_content": "\n",
        "formatted_description": "
test!
\n",
        "like_count": "1",
        "comment_count": "0",
        "snaps": {
          "mega_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/mega.png?1296504621",
          "keith_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/keith.png?1296504621",
          "large_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/large.png?1296504621",
          "medium_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/medium.png?1296504621",
          "small_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/small.png?1296504621",
          "thumb_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/thumb.png?1296504621",
          "original_url": "http://forrst-development.s3.amazonaws.com/posts/snaps/45146/original.png?1296504621"
        }
      },
      ...snip...
    ],
    "page": 1
  },
  "stat": "ok",
  "in": 0.1557,
  "authed": false,
  "authed_as": false,
  "env": "dev"
}

post/comments

Returns a post's comments

Type: Read
Method: GET
Must Authenticate? Yes
Params:
  • id: Post ID
  • tiny_id: Post Tiny ID

Sample Response: 
{
  "resp": {
    "comments": [
      {
        "id": 22056,
        "user": {
          ...snip...
        },
        "body": "...",
        "created_at": "2010-06-30 14:59:45",
        "updated_at": "2010-06-30 14:59:45"
      },
      ...snip...
    ],
    "count": 24
  },
  "stat": "ok",
  "in": 0.3883,
  "authed": true,
  "authed_as": [
    1,
    "kyle"
  ],
  "env": "dev"
}
Get Updates
Follow kylebragger on Twitter

Stats
5,864,699 total requests
52,391 requests this week
15,536 requests today
3 new notifications