Initial commit of the DN API docs

01_Introduction.md

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

02_Getting_Started.md

@@ -0,0 +1,6 @@
+## Getting Started
+
+0. Please send an email to news@layervault.com to request your API credentials. Please include your callback URL. One day, this might be automated.
+0. Receive a friendly note back from the LayerVault staff with your application credentials.
+0. Note your ```client_id``` and ```client_secret```.
+0. Try the example Access Token request below.

03_API_Endpoint.md

@@ -0,0 +1,2 @@
+### API Endpoint
+https://news.layervault.com/api/v1

04_Summary_of_Resource_URL_Patterns.md

@@ -0,0 +1,11 @@
+### Summary of Resource URL Patterns
+
+    /api/v1/me
+    /api/v1/stories/recent
+    /api/v1/stories/search
+    /api/v1/stories/:id/upvote
+    /api/v1/stories
+    /api/v1/stories/:id
+    /api/v1/comments/:id/upvote(.:format
+    /api/v1/comments/:id/reply
+    /api/v1/comments/:id

05_URL_Parameters.md

@@ -0,0 +1,3 @@
+### URL Parameters
+    :id    - The ID of the resource
+    :page  - The page of the resources

06_Authentication_and_Requesting_Access_Tokens.md

@@ -0,0 +1,22 @@
+## Authentication and Requesting Access Tokens
+
+All API requests are required to be 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:
+
+```shell
+curl -i https://api.news.layervault.com/oauth/token \
+  -F grant_type="password" \
+  -F username="<your Designer News username>" \
+  -F password="<your Designre 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:
+
+```json
+{
+  "access_token":"aec9c670cf5e673bfedf83d055d2a2e0e5f37e52d3b41cffcf7874f73a7458bf",
+  "token_type":"bearer",
+  "scope":"user"
+}
+```

07_Configuring_a_Web_Application.md

@@ -0,0 +1,5 @@
+### Configuring A Web Application as a LayerVault 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.

08_Making_API_Calls.md

@@ -0,0 +1,7 @@
+## Making API Calls
+
+Once you have your access token, making some API calls from the command line is also easy:
+
+```shell
+curl -H 'Authorization: Bearer <your access token>' 'https://api.news.layervault.com/api/v1/me'
+```

09_Versioning.md

@@ -0,0 +1,3 @@
+## Versioning
+
+Currently, the LayerVault 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.

10_Rate_Limits.md

@@ -0,0 +1,8 @@
+## 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](mailto:support@layervault.com) and we'll do our best to accommodate you.

11_Users.md

@@ -0,0 +1,27 @@
+### 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
+
+```json
+{
+  "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"
+  }
+}
+```

12_Stories.md

@@ -0,0 +1,66 @@
+### Stories
+
+#### Retrieving Story Information
+
+This call returns information for a story.
+
+ Definition
+
+    GET /api/v1/stories/:id
+
+ Example Request
+
+    $ curl -H 'Authorization: Bearer <your access token>' 'https://api.news.layervault.com/api/v1/stories/:id'
+
+ Example Response
+
+```json
+{
+  "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 will 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 -H 'Authorization: Bearer <your access token>' 'https://api.news.layervault.com/api/v1/stories'
+
+ Example Response
+
+```json
+{
+  "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
+    }
+  ]
+}
+```

README.md

@@ -0,0 +1,2 @@
+## Please see each individual chapter file.
+