Designer News API Reference

Introduction

The Designer News API provides a simple HTTP based REST based mechanism for interacting with Designer News and allowing applications to access user information via oAuth 2 authenticated requests, over SSL. API responses are simple JSON objects.

Getting Started

  1. Please send an email to news@layervault.com to request your API credentials. Please include your callback URL and Designer News user ID. One day, this might be automated.
  2. Receive a friendly note back from the LayerVault staff with your application credentials.
  3. Note your client_id and client_secret.
  4. Try the example Access Token request below.

API Endpoint

https://api-news.layervault.com/api/v1

Summary of Resource URL Patterns

/api/v1/me
/api/v1/stories/recent
/api/v1/stories/search
/api/v1/stories/:id/upvote
/api/v1/stories/:id/reply
/api/v1/stories
/api/v1/stories/:id
/api/v1/comments/:id/upvote
/api/v1/comments/:id/reply
/api/v1/comments/:id
/api/v1/motd/upvote
/api/v1/motd/downvote
/api/v1/motd

URL Parameters

:id    - The ID of the resource
:page  - The page of the resources

Authentication and Requesting Access Tokens

All endpoints require authentication of some form.

GET Endpoints

GET endpoints do not require user authentication, but they do require at the least application authentication. This means that either an OAuth client ID or a user access token must be present. To make a request with a client ID, simply send it as a GET parameter, like this:

curl https://api-news.layervault.com/api/v1/stories?client_id=91a5fed537b58c60f36be1sdf71ed1320e9e4af2bda4366f7dn3d79e63835278

POST requests

All API POST requests are required to be user authenticated via an oAuth 2 access token. It’s easy to request a token via the command line to get a feel for how things work:

curl -i https://api-news.layervault.com/oauth/token \
  -F grant_type="password" \
  -F username="<your Designer News username>" \
  -F password="<your Designer News password>" \
  -F client_id="<client_id_goes_here>" \
  -F client_secret="<client_secret_goes_here>"

Which will return an Access token response like this one:

{
  "access_token":"aec9c670cf5e673bfedf83d055d2a2e0e5f37e52d3b41cffcf7874f73a7458bf",
  "token_type":"bearer",
  "scope":"user"
}

The access token must then be passed in the Authorization header for all POST requests. See examples below for more information.

Configuring A Web Application as a Designer News API client

First of all, make sure that your redirect URI is correctly specified.

Then, when configuring your oAuth 2 client library, tell it to use https://api-news.layervault.com/oauth/authorize to request authorization and https://api-news.layervault.com/oauth/token to get access tokens. Most libraries will default to this convention anyway.

Making API Calls

Once you have your access token, making some API calls from the command line is also easy. For authenticated requests, which require an Authorization header:

curl -H 'Authorization: Bearer <your access token>' \
  'https://api-news.layervault.com/api/v1/me'

For unauthenticated requests, the Designer News API is setup with Cross-Origin Resource Sharing (CORS) rules that allow you to access it from any domain without using something like JSONP.

Versioning

Currently, the Designer News API is versioned with a URL segment, such as /v1/. The current production version of the API is Version 1, so your calls should use /v1/ as the version segment.

Rate Limits

The API currently limits the requests you can make against it hourly. We have provided two response headers with each request to the API with Rate Limiting Information. They are returned from every API call.

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299

X-RateLimit-Limit is your current limit per hour. X-RateLimit-Remaining is how many requests you have left. If you need more requests than 300/hr, please contact us and we’ll do our best to accommodate you.

User Information

Retrieving User Information

This call returns the user information for which the Client is acting on behalf of.

Definition

GET /api/v1/me

Example Request

$ curl -H 'Authorization: Bearer <your access token>' \
  'https://api-news.layervault.com/api/v1/me'

Example Response

{
  "me": {
    "created_at": "2012-11-15T04:48:45Z",
    "first_name": "Kelly",
    "job": "Founder at LayerVault",
    "last_name": "Sutton",
    "portrait_url": "https://news.layervault.com/cats.gif"
  }
}

Retrieving Information About Other Users

This call returns information about the requested user.

Definition

GET /api/v1/users/:id

Example Request

$ curl -H 'Authorization: Bearer <your access token>' \
  'https://api-news.layervault.com/api/v1/users/1'

Example Response

{
  "me": {
    "created_at": "2012-11-15T04:48:45Z",
    "first_name": "Kelly",
    "job": "Founder at LayerVault",
    "last_name": "Sutton",
    "portrait_url": "https://news.layervault.com/cats.gif",
    "cover_photo_url": "https://news.layervault.com/dogs.gif"
  }
}

Stories

Retrieving Story Information

This call returns information for a story.

Definition

GET /api/v1/stories/:id

Example Request

$ curl 'https://api-news.layervault.com/api/v1/stories/:id?client_id=abc123'

Example Response

{
  "story": {
    "comment": "",
    "comments": [
        ...
    ],
    "created_at": "2014-01-24T17:15:19Z",
    "id": 13627,
    "site_url": "http://localhost:3000/stories/13627-a-logo-should-tell-a-story",
    "title": "A logo should tell a story.",
    "url": "http://localhost:3000/click/stories/13627",
    "vote_count": 11
  }
}

Retrieving the front page

This call returns a list of stories on the set page. Note: Page numbering starts at 1. If not specified, the default page will be 1.

Definition

GET /api/v1/stories

Example Request

$ curl 'https://api-news.layervault.com/api/v1/stories?client_id=abc123'

Example Response

{
  "stories": [
    {
      "comment": "",
      "comments": [
          ...
      ],
      "created_at": "2014-01-24T17:15:19Z",
      "id": 13627,
      "site_url": "http://localhost:3000/stories/13627-a-logo-should-tell-a-story",
      "title": "A logo should tell a story.",
      "url": "http://localhost:3000/click/stories/13627",
      "vote_count": 11
    },
    ...
  ]
}

Retrieving recent stories

This call returns the content of the most Designer News recent stories, offset by a page number. Note: Page numbering starts at 1. If not specified, the default page will be 1.

Definition

GET /api/v1/stories/recent

Example Request

$ curl 'https://api-news.layervault.com/api/v1/stories/recent?client_id=abc123'

Example Response

{
  "stories": [
    {
      "comment": "",
      "comments": [
          ...
      ],
      "created_at": "2014-01-24T17:15:19Z",
      "id": 13627,
      "site_url": "http://localhost:3000/stories/13627-a-logo-should-tell-a-story",
      "title": "A logo should tell a story.",
      "url": "http://localhost:3000/click/stories/13627",
      "vote_count": 11
    },
    ...
  ]
}

Upvoting a Story

This call will upvote a Story on a user’s behalf. This can only be called once per user. Abuses of upvoting will get your app banned.

Definition

POST /api/v1/stories/:id/upvote

Example Request

$ curl -X POST -H 'Authorization: Bearer <your access token>' \
  'https://api-news.layervault.com/api/v1/stories/13627/upvote'

Example Response

{
  "story": {
    "comment": "",
    "comments": [
        ...
    ],
    "created_at": "2014-01-24T17:15:19Z",
    "id": 13627,
    "site_url": "https://news.layervault.com/stories/13627-a-logo-should-tell-a-story",
    "title": "A logo should tell a story.",
    "url": "https://news.layervault.com/click/stories/13627",
    "vote_count": 12
  }
}

Commenting on a Story

This call will create a new comment on behalf of the user and attach it to the story specified. It returns the comment that was just created, or an error code.

Definition

POST /api/v1/stories/:id/reply

Example Request

$ curl -X POST \
  -d 'comment[body]=Kicking off the conversation.' \
  -H 'Authorization: Bearer <your access token>' \
  'https://api-news.layervault.com/api/v1/stories/36524/reply'

Example Response

{
  "comment": {
    "body": "Kicking off the conversation.",
    "comments": [],
    "created_at": "2014-01-24T16:53:08Z",
    "depth": 0,
    "id": 9000,
    "vote_count": 0,
    "url": "https://news.layervault.com/comments/9000",
    "user_display_name": "Kelly S.",
    "user_id": 1
  }
}

Searching for Stories

This call will search through Designer News stories and return any matching stories. Searches are specified with a query parameter

Definition

GET /api/v1/stories/search

Example Request

$ curl 'https://api-news.layervault.com/api/v1/stories/search?query=Kelly%20Sutton&client_id=abc123'

Example Response

{
  "stories": [
    {
      "comment": "",
      "comments": [
          ...
      ],
      "created_at": "2014-01-24T17:15:19Z",
      "id": 13627,
      "site_url": "http://localhost:3000/stories/13627-a-logo-should-tell-a-story",
      "title": "Kelly Sutton is pretty cool, I guess.",
      "url": "http://localhost:3000/click/stories/13627",
      "vote_count": 11
    },
    ...
  ]
}

Comments

Retrieving Comment Information

This call returns information for a comment.

Definition

GET /api/v1/comments/:id

Example Request

$ curl 'https://api-news.layervault.com/api/v1/comments/36524?client_id=abc123'

Example Response

{
  "comment": {
    "body": "I would try something other than blue. Purples can be nice depending on how you approach brand design.\r\n\r\nOne often overlooked approach is blank and white. Most companies could benefit from using some shades of grey as the main brand color. You could have accent colours like blue, purple or orange, but mainly back and white.\r\n\r\nThe fun thing about B&W is that it convey simplicity and clarity, without losing its inherited old trust. Definitely worth trying out.\r\n\r\nBut, more than anything I could say, try crazy things. Set aside 20% of the time you dedicate to this project and try other colours: Red, orange, green. You'll be surprised by how testing some crazy ideas can improve your process and, if they don't work in the end, they will sure reflect on your final choice.",
    "comments": [],
    "created_at": "2014-01-24T16:53:08Z",
    "depth": 2,
    "id": 36524,
    "vote_count": 0,
    "url": "https://news.layervault.com/comments/36524",
    "user_display_name": "Matt P.",
    "user_id": 4181
  }
}

Replying to a Comment

This call will create a new comment on behalf of the user and attach it to the comment specified. It returns the comment that was just created, or an error code.

Definition

POST /api/v1/comments/:id/reply

Example Request

$ curl -X POST \
  -d 'comment[body]=I agree. Purples are sweet.' \
  -H 'Authorization: Bearer <your access token>' \
  'https://api-news.layervault.com/api/v1/comments/36524/reply'

Example Response

{
  "comment": {
    "body": "I agree. Purples are sweet.",
    "comments": [],
    "created_at": "2014-01-24T16:53:08Z",
    "depth": 3,
    "id": 9001,
    "vote_count": 0,
    "url": "https://news.layervault.com/comments/9001",
    "user_display_name": "Kelly S.",
    "user_id": 1
  }
}

Upvoting a Comment

This call will upvote a comment on behalf of the current user. It returns the comment that was upvoted, with an updated vote_count.

Definition

POST /api/v1/comments/:id/upvote

Example Request

$ curl -H 'Authorization: Bearer <your access token>' \
  'https://api-news.layervault.com/api/v1/comments/36524/upvote'

Example Response

{
  "comment": {
    "body": "I would try something other than blue. Purples can be nice depending on how you approach brand design.\r\n\r\nOne often overlooked approach is blank and white. Most companies could benefit from using some shades of grey as the main brand color. You could have accent colours like blue, purple or orange, but mainly back and white.\r\n\r\nThe fun thing about B&W is that it convey simplicity and clarity, without losing its inherited old trust. Definitely worth trying out.\r\n\r\nBut, more than anything I could say, try crazy things. Set aside 20% of the time you dedicate to this project and try other colours: Red, orange, green. You'll be surprised by how testing some crazy ideas can improve your process and, if they don't work in the end, they will sure reflect on your final choice.",
    "comments": [],
    "created_at": "2014-01-24T16:53:08Z",
    "depth": 2,
    "id": 36524,
    "upvotes_count": 1,
    "url": "https://news.layervault.com/comments/36524",
    "user_display_name": "Matt P.",
    "user_id": 4181
  }
}

MOTD

Retrieving MOTD information

This call returns information for the current MOTD (message of the day).

Definition

GET /api/v1/motd

Example Request

$ curl 'https://api-news.layervault.com/api/v1/motd?client_id=abc123'

Example Response

{
  "motd": {
    "downvote_count": 0,
    "message": "What was your first Mac? https://www.apple.com/30-years/your-first-mac/",
    "upvote_count": 6,
    "user_display_name": "Wells R.",
    "user_id": 272
  }
}

Upvoting an MOTD

This call upvotes the current MOTD.

Definition

POST /api/v1/motd/upvote

Example Request

$ curl -H 'Authorization: Bearer <your access token>' \
  -X POST \
  'https://api-news.layervault.com/api/v1/motd/upvote'

Example Response

{
  "motd": {
    "downvote_count": 0,
    "message": "What was your first Mac? https://www.apple.com/30-years/your-first-mac/",
    "upvote_count": 7,
    "user_display_name": "Wells R.",
    "user_id": 272
  }
}

Downvoting an MOTD

This call downvote the current MOTD.

Definition

POST /api/v1/motd/downvote

Example Request

$ curl -H 'Authorization: Bearer <your access token>' \
  -X POST \
  'https://api-news.layervault.com/api/v1/motd/downvote'

Example Response

{
  "motd": {
    "downvote_count": 1,
    "message": "What was your first Mac? https://www.apple.com/30-years/your-first-mac/",
    "upvote_count": 6,
    "user_display_name": "Wells R.",
    "user_id": 272
  }
}