From d90d2d697946eafdb59cf57778e72882ee5de97b Mon Sep 17 00:00:00 2001 From: Kelly Sutton Date: Tue, 11 Feb 2014 10:03:11 -0500 Subject: [PATCH] Initial commit of the DN API docs --- 01_Introduction.md | 2 + 02_Getting_Started.md | 6 ++ 03_API_Endpoint.md | 2 + 04_Summary_of_Resource_URL_Patterns.md | 11 ++++ 05_URL_Parameters.md | 3 + ...entication_and_Requesting_Access_Tokens.md | 22 +++++++ 07_Configuring_a_Web_Application.md | 5 ++ 08_Making_API_Calls.md | 7 ++ 09_Versioning.md | 3 + 10_Rate_Limits.md | 8 +++ 11_Users.md | 27 ++++++++ 12_Stories.md | 66 +++++++++++++++++++ README.md | 2 + 13 files changed, 164 insertions(+) create mode 100644 01_Introduction.md create mode 100644 02_Getting_Started.md create mode 100644 03_API_Endpoint.md create mode 100644 04_Summary_of_Resource_URL_Patterns.md create mode 100644 05_URL_Parameters.md create mode 100644 06_Authentication_and_Requesting_Access_Tokens.md create mode 100644 07_Configuring_a_Web_Application.md create mode 100644 08_Making_API_Calls.md create mode 100644 09_Versioning.md create mode 100644 10_Rate_Limits.md create mode 100644 11_Users.md create mode 100644 12_Stories.md create mode 100644 README.md diff --git a/01_Introduction.md b/01_Introduction.md new file mode 100644 index 0000000..0ba9e89 --- /dev/null +++ b/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. diff --git a/02_Getting_Started.md b/02_Getting_Started.md new file mode 100644 index 0000000..995320d --- /dev/null +++ b/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. diff --git a/03_API_Endpoint.md b/03_API_Endpoint.md new file mode 100644 index 0000000..1dad2b4 --- /dev/null +++ b/03_API_Endpoint.md @@ -0,0 +1,2 @@ +### API Endpoint +https://news.layervault.com/api/v1 diff --git a/04_Summary_of_Resource_URL_Patterns.md b/04_Summary_of_Resource_URL_Patterns.md new file mode 100644 index 0000000..c5dc032 --- /dev/null +++ b/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 diff --git a/05_URL_Parameters.md b/05_URL_Parameters.md new file mode 100644 index 0000000..ac3ae2a --- /dev/null +++ b/05_URL_Parameters.md @@ -0,0 +1,3 @@ +### URL Parameters + :id - The ID of the resource + :page - The page of the resources diff --git a/06_Authentication_and_Requesting_Access_Tokens.md b/06_Authentication_and_Requesting_Access_Tokens.md new file mode 100644 index 0000000..d4ba1ba --- /dev/null +++ b/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="" \ + -F password="" \ + -F client_id="" \ + -F client_secret="" +``` + +Which will return an Access token response like this one: + +```json +{ + "access_token":"aec9c670cf5e673bfedf83d055d2a2e0e5f37e52d3b41cffcf7874f73a7458bf", + "token_type":"bearer", + "scope":"user" +} +``` diff --git a/07_Configuring_a_Web_Application.md b/07_Configuring_a_Web_Application.md new file mode 100644 index 0000000..8f9c654 --- /dev/null +++ b/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. diff --git a/08_Making_API_Calls.md b/08_Making_API_Calls.md new file mode 100644 index 0000000..f78f9d2 --- /dev/null +++ b/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 ' 'https://api.news.layervault.com/api/v1/me' +``` diff --git a/09_Versioning.md b/09_Versioning.md new file mode 100644 index 0000000..626efd1 --- /dev/null +++ b/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. diff --git a/10_Rate_Limits.md b/10_Rate_Limits.md new file mode 100644 index 0000000..1640ffc --- /dev/null +++ b/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. diff --git a/11_Users.md b/11_Users.md new file mode 100644 index 0000000..95f2959 --- /dev/null +++ b/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 ' '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" + } +} +``` \ No newline at end of file diff --git a/12_Stories.md b/12_Stories.md new file mode 100644 index 0000000..43c3515 --- /dev/null +++ b/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 ' '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 ' '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 + } + ] +} +``` \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..65cc211 --- /dev/null +++ b/README.md @@ -0,0 +1,2 @@ +## Please see each individual chapter file. +