{"_id":"5523ceb87a46cc1700026b52","version":{"_id":"550ada9d921b7d0d00228876","forked_from":"550a3b2542fff40d00ae5ffb","project":"550a379f635c660d00527fd8","__v":3,"createdAt":"2015-03-19T14:18:05.245Z","releaseDate":"2015-03-19T14:18:05.245Z","categories":["550ada9d921b7d0d00228877","550ada9d921b7d0d00228878","550ada9d921b7d0d00228879","550ada9d921b7d0d0022887a","550ada9d921b7d0d0022887b","550ada9d921b7d0d0022887c","550ada9d921b7d0d0022887d","5523e61e71c0542100993493","55246f72ccc28a0d0062c560"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3.0.0"},"category":{"_id":"550ada9d921b7d0d00228879","version":"550ada9d921b7d0d00228876","__v":4,"pages":["550ada9e921b7d0d00228882","550ada9e921b7d0d00228883","550ada9e921b7d0d00228884","550ada9e921b7d0d00228885","55235488b4a0de0d00de800f","5523ceb87a46cc1700026b52","5523e1117a36b22b0088654b"],"project":"550a379f635c660d00527fd8","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-03-19T02:50:29.906Z","from_sync":false,"order":1,"slug":"getting-started","title":"Getting Started"},"user":"550a378e635c660d00527fd7","__v":33,"project":"550a379f635c660d00527fd8","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-04-07T12:34:00.935Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"This guide is intended for those that are new to reddit development & JavaScript. If you have experience with both take a look at the [Quick Example](doc:quick-example) and the [Making a call](doc:making-a-call) sections for a quicker start.\",\n  \"title\": \"Before you begin\"\n}\n[/block]\nWe will be using Node.js in this guide to create a simple reddit bot. The same concepts can be used in browser based JavaScript with some exceptions (See [Node vs. Browser](doc:node-vs-browser)).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1 Create a reddit application\"\n}\n[/block]\nCreate a script based application. Follow [this guide](https://github.com/reddit/reddit/wiki/OAuth2-Quick-Start-Example) from reddit.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2 Setup a new project\"\n}\n[/block]\nCreate a new directory for this beginners guide. Install Snoocore in that directory: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"npm install snoocore\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"3 Create the main file\"\n}\n[/block]\nThis application will be simple & contained in a single file. Create a new file `app.js` inside of your new project directory created in section 2.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"4 Setup a Snoocore instance\"\n}\n[/block]\nIn `app.js`, require Snoocore:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var Snoocore = require('snoocore');\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nA [new instance](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Introduction_to_Object-Oriented_JavaScript#The_Object_.28Class_Instance.29) of Snoocore is required to make a call to reddit. Every instance of Snoocore (`new Snoocore`) should be associated with a single account.\n\nMaking a new instance requires some parameters. A complete list of parameters can be found in the [Configuration Options](doc:configuration-options). For the purposes of this guide they will be explained here.\n\nCreating the instance:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Our new instance associated with a single account.\\n// It takes in various configuration options.\\nvar reddit = new Snoocore({\\n  userAgent: '/u/username myApp:::at:::3.0.0', // unique string identifying the app\\n  oauth: {\\n  \\ttype: 'script',\\n    key: '', // OAuth client key (provided at reddit app)\\n    secret: '', // OAuth secret (provided at reddit app)\\n    username: '', // Reddit username used to make the reddit app\\n    password: '', // Reddit password for the username\\n    // The OAuth scopes that we need to make the calls that we \\n    // want. The reddit documentation will specify which scope\\n    // is needed for evey call\\n    scope: [ 'identity', 'read', 'vote' ]\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"5 Making the first call\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"All calls return [promises](https://promisesaplus.com/). Make sure to understand how they work before moving on in the guide.\",\n  \"title\": \"Promises\"\n}\n[/block]\n\n\nThis library maps calls directly to the reddit API. This will hopefully make more sense with a few examples. View the [Making a call](doc:making-a-call) page for more information.\n\nThe basic formula is:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/*\\nAll HTTP verbs are supporded:\\n\\nThe `.get` can be replaced with: `.post`, `.delete`, `.patch`, etc.\\n*/\\n\\nvar promise = reddit('/path/to/endpoint').get({/*\\n\\tArguments for this endpoint can be passed \\n  in here as a javascript object.\\n*/});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nUsing the endpoint [`GET /api/v1/me`](https://www.reddit.com/dev/api#GET_api_v1_me):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"reddit('/api/v1/me').get().then(function(result) {\\n  console.log(result); \\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nThis is the current code so far:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var Snoocore = require('snoocore');\\n\\n// Our new instance associated with a single account.\\n// It takes in various configuration options.\\nvar reddit = new Snoocore({\\n  userAgent: '/u/username myApp@3.0.0', // unique string identifying the app\\n  oauth: {\\n  \\ttype: 'script',\\n    key: '', // OAuth client key (provided at reddit app)\\n    secret: '', // OAuth secret (provided at reddit app)\\n    username: '', // Reddit username used to make the reddit app\\n    password: '', // Reddit password for the username\\n    // The OAuth scopes that we need to make the calls that we \\n    // want. The reddit documentation will specify which scope\\n    // is needed for evey call\\n    scope: [ 'identity', 'read', 'vote' ]\\n  }\\n});\\n\\nreddit('/api/v1/me').get().then(function(result) {\\n  console.log(result); \\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Make sure this works!\",\n  \"body\": \"Fill in your values in the blanks, save as `app.js`, and run the code:\\n\\n```\\nnode app.js\\n```\\n\\nIt should write the authenticated users information to the console.\\n\\n- - -\\n\\nIf you are running into errors, double check that your information (username, password, key, secret, etc.) are correct. If it still isn't working feel free to ask on Gitter chat.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"6 Making additional calls\"\n}\n[/block]\nThis section will demonstrate how to make various calls to the reddit API.\n\n#### 5.2 Get the second page of a subreddit\n\nUsing the endpooint [`GET [/r/subreddit]/hot` (link)](https://www.reddit.com/dev/api#GET_hot):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"reddit('/r/askreddit/hot').get().then(function(result) {\\n  console.log(result); \\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nThis works to get the first page of /r/askreddit, but it can be tedious navigating through a listing. \n\nTo help with this, Snoocore has various helpers that can be used *inplace* of the basic HTTP verbs. The listing helper will make getting to the second page easier (For more information, see [Listings](doc:listings)). Read the following code & comments to get an understanding of what is going on:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Instead of an HTTP verb, use a Snoocore helper `.listing`\\n// It will return a \\\"slice\\\" for a listing that has various \\n// helpers attached to it.\\nreddit('/r/askreddit/hot').listing().then(function(slice) {\\n  \\n  // This is the front page of /r/askreddit\\n  // `slice.children` contains the contents of the page.\\n  console.log(slice.children);\\n  \\n  // Get a promise for the next slice in this \\n  // listing (the next page!)\\n  return slice.next();\\n  \\n}).then(function(slice) {\\n  \\n  // This is the second page of /r/askreddit\\n  console.log(slice.children);\\n  \\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## 5.3 Voting on a post\n\nUsing the endpoint [`POST /api/vote`](https://www.reddit.com/dev/api#POST_api_vote):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"reddit('/api/vote').post({\\n  dir: 1, // upvote!\\n  id: 'fullname-of-a-thing'\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nFullnames can be hard to understand at first. The reddit documentation [explains what they are](https://www.reddit.com/dev/api#fullnames). *Section 7 - Bringing it all together* will show an example of how this endpoint can be used to upvote a post.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"7 Bringing it all together\"\n}\n[/block]\nThe following code will:\n\n1. Log information about the authenticated user\n2. Print the content of the second page of /r/askreddit\n3. Upvote the first post on the second page of /r/askreddit\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var Snoocore = require('snoocore');\\n\\n// Our new instance associated with a single account.\\n// It takes in various configuration options.\\nvar reddit = new Snoocore({\\n  userAgent: '/u/username myApp@3.0.0', // unique string identifying the app\\n  oauth: {\\n    type: 'script',\\n    key: '',\\n    secret: '',\\n    username: '',\\n    password: '',\\n    // The OAuth scopes that we need to make the calls that we\\n    // want. The reddit documentation will specify which scope\\n    // is needed for evey call\\n    scope: [ 'identity', 'read', 'vote' ]\\n  }\\n});\\n\\nreddit('/api/v1/me').get().then(function(result) {\\n  console.log('/u/' + result.name);\\n  // get a promise for a listing of /r/askreddit\\n  return reddit('/r/askreddit/hot').listing();\\n}).then(function(slice) {\\n  // Get a promise for the next slice in this\\n  // listing (the second page!)\\n  return slice.next();\\n}).then(function(slice) {\\n  // This is the second page of /r/askreddit\\n\\n  var firstSubmission = slice.children[0];\\n\\n  console.log('upvoting post:');\\n  console.log(firstSubmission.data.title);\\n  console.log(firstSubmission.data.url);\\n\\n  // Let's upvote the first thing on the second page:\\n  return reddit('/api/vote').post({\\n    dir: 1, // upvote!\\n    id: firstSubmission.kind + '_' + firstSubmission.data.id // e.g. t3_345jur\\n  });\\n}).then(function() {\\n  console.log('done! checkout the link to see that it is really upvoted.');\\n});\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Finished!\",\n  \"body\": \"If you have any questions feel free to hop on [Gitter](https://gitter.im/trevorsenior/snoocore) and ask!\"\n}\n[/block]","excerpt":"We all have to start somewhere.","slug":"beginners-guide","type":"basic","title":"Beginners Guide"}

Beginners Guide

We all have to start somewhere.

[block:callout] { "type": "info", "body": "This guide is intended for those that are new to reddit development & JavaScript. If you have experience with both take a look at the [Quick Example](doc:quick-example) and the [Making a call](doc:making-a-call) sections for a quicker start.", "title": "Before you begin" } [/block] We will be using Node.js in this guide to create a simple reddit bot. The same concepts can be used in browser based JavaScript with some exceptions (See [Node vs. Browser](doc:node-vs-browser)). [block:api-header] { "type": "basic", "title": "1 Create a reddit application" } [/block] Create a script based application. Follow [this guide](https://github.com/reddit/reddit/wiki/OAuth2-Quick-Start-Example) from reddit. [block:api-header] { "type": "basic", "title": "2 Setup a new project" } [/block] Create a new directory for this beginners guide. Install Snoocore in that directory: [block:code] { "codes": [ { "code": "npm install snoocore", "language": "shell" } ] } [/block] [block:api-header] { "type": "basic", "title": "3 Create the main file" } [/block] This application will be simple & contained in a single file. Create a new file `app.js` inside of your new project directory created in section 2. [block:api-header] { "type": "basic", "title": "4 Setup a Snoocore instance" } [/block] In `app.js`, require Snoocore: [block:code] { "codes": [ { "code": "var Snoocore = require('snoocore');", "language": "javascript" } ] } [/block] A [new instance](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Introduction_to_Object-Oriented_JavaScript#The_Object_.28Class_Instance.29) of Snoocore is required to make a call to reddit. Every instance of Snoocore (`new Snoocore`) should be associated with a single account. Making a new instance requires some parameters. A complete list of parameters can be found in the [Configuration Options](doc:configuration-options). For the purposes of this guide they will be explained here. Creating the instance: [block:code] { "codes": [ { "code": "// Our new instance associated with a single account.\n// It takes in various configuration options.\nvar reddit = new Snoocore({\n userAgent: '/u/username myApp@3.0.0', // unique string identifying the app\n oauth: {\n \ttype: 'script',\n key: '', // OAuth client key (provided at reddit app)\n secret: '', // OAuth secret (provided at reddit app)\n username: '', // Reddit username used to make the reddit app\n password: '', // Reddit password for the username\n // The OAuth scopes that we need to make the calls that we \n // want. The reddit documentation will specify which scope\n // is needed for evey call\n scope: [ 'identity', 'read', 'vote' ]\n }\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "5 Making the first call" } [/block] [block:callout] { "type": "warning", "body": "All calls return [promises](https://promisesaplus.com/). Make sure to understand how they work before moving on in the guide.", "title": "Promises" } [/block] This library maps calls directly to the reddit API. This will hopefully make more sense with a few examples. View the [Making a call](doc:making-a-call) page for more information. The basic formula is: [block:code] { "codes": [ { "code": "/*\nAll HTTP verbs are supporded:\n\nThe `.get` can be replaced with: `.post`, `.delete`, `.patch`, etc.\n*/\n\nvar promise = reddit('/path/to/endpoint').get({/*\n\tArguments for this endpoint can be passed \n in here as a javascript object.\n*/});", "language": "javascript" } ] } [/block] Using the endpoint [`GET /api/v1/me`](https://www.reddit.com/dev/api#GET_api_v1_me): [block:code] { "codes": [ { "code": "reddit('/api/v1/me').get().then(function(result) {\n console.log(result); \n});", "language": "javascript" } ] } [/block] This is the current code so far: [block:code] { "codes": [ { "code": "var Snoocore = require('snoocore');\n\n// Our new instance associated with a single account.\n// It takes in various configuration options.\nvar reddit = new Snoocore({\n userAgent: '/u/username myApp@3.0.0', // unique string identifying the app\n oauth: {\n \ttype: 'script',\n key: '', // OAuth client key (provided at reddit app)\n secret: '', // OAuth secret (provided at reddit app)\n username: '', // Reddit username used to make the reddit app\n password: '', // Reddit password for the username\n // The OAuth scopes that we need to make the calls that we \n // want. The reddit documentation will specify which scope\n // is needed for evey call\n scope: [ 'identity', 'read', 'vote' ]\n }\n});\n\nreddit('/api/v1/me').get().then(function(result) {\n console.log(result); \n});", "language": "javascript" } ] } [/block] [block:callout] { "type": "danger", "title": "Make sure this works!", "body": "Fill in your values in the blanks, save as `app.js`, and run the code:\n\n```\nnode app.js\n```\n\nIt should write the authenticated users information to the console.\n\n- - -\n\nIf you are running into errors, double check that your information (username, password, key, secret, etc.) are correct. If it still isn't working feel free to ask on Gitter chat." } [/block] [block:api-header] { "type": "basic", "title": "6 Making additional calls" } [/block] This section will demonstrate how to make various calls to the reddit API. #### 5.2 Get the second page of a subreddit Using the endpooint [`GET [/r/subreddit]/hot` (link)](https://www.reddit.com/dev/api#GET_hot): [block:code] { "codes": [ { "code": "reddit('/r/askreddit/hot').get().then(function(result) {\n console.log(result); \n});", "language": "javascript" } ] } [/block] This works to get the first page of /r/askreddit, but it can be tedious navigating through a listing. To help with this, Snoocore has various helpers that can be used *inplace* of the basic HTTP verbs. The listing helper will make getting to the second page easier (For more information, see [Listings](doc:listings)). Read the following code & comments to get an understanding of what is going on: [block:code] { "codes": [ { "code": "// Instead of an HTTP verb, use a Snoocore helper `.listing`\n// It will return a \"slice\" for a listing that has various \n// helpers attached to it.\nreddit('/r/askreddit/hot').listing().then(function(slice) {\n \n // This is the front page of /r/askreddit\n // `slice.children` contains the contents of the page.\n console.log(slice.children);\n \n // Get a promise for the next slice in this \n // listing (the next page!)\n return slice.next();\n \n}).then(function(slice) {\n \n // This is the second page of /r/askreddit\n console.log(slice.children);\n \n});", "language": "javascript" } ] } [/block] ## 5.3 Voting on a post Using the endpoint [`POST /api/vote`](https://www.reddit.com/dev/api#POST_api_vote): [block:code] { "codes": [ { "code": "reddit('/api/vote').post({\n dir: 1, // upvote!\n id: 'fullname-of-a-thing'\n});", "language": "javascript" } ] } [/block] Fullnames can be hard to understand at first. The reddit documentation [explains what they are](https://www.reddit.com/dev/api#fullnames). *Section 7 - Bringing it all together* will show an example of how this endpoint can be used to upvote a post. [block:api-header] { "type": "basic", "title": "7 Bringing it all together" } [/block] The following code will: 1. Log information about the authenticated user 2. Print the content of the second page of /r/askreddit 3. Upvote the first post on the second page of /r/askreddit [block:code] { "codes": [ { "code": "var Snoocore = require('snoocore');\n\n// Our new instance associated with a single account.\n// It takes in various configuration options.\nvar reddit = new Snoocore({\n userAgent: '/u/username myApp@3.0.0', // unique string identifying the app\n oauth: {\n type: 'script',\n key: '',\n secret: '',\n username: '',\n password: '',\n // The OAuth scopes that we need to make the calls that we\n // want. The reddit documentation will specify which scope\n // is needed for evey call\n scope: [ 'identity', 'read', 'vote' ]\n }\n});\n\nreddit('/api/v1/me').get().then(function(result) {\n console.log('/u/' + result.name);\n // get a promise for a listing of /r/askreddit\n return reddit('/r/askreddit/hot').listing();\n}).then(function(slice) {\n // Get a promise for the next slice in this\n // listing (the second page!)\n return slice.next();\n}).then(function(slice) {\n // This is the second page of /r/askreddit\n\n var firstSubmission = slice.children[0];\n\n console.log('upvoting post:');\n console.log(firstSubmission.data.title);\n console.log(firstSubmission.data.url);\n\n // Let's upvote the first thing on the second page:\n return reddit('/api/vote').post({\n dir: 1, // upvote!\n id: firstSubmission.kind + '_' + firstSubmission.data.id // e.g. t3_345jur\n });\n}).then(function() {\n console.log('done! checkout the link to see that it is really upvoted.');\n});\n", "language": "javascript" } ] } [/block] [block:callout] { "type": "success", "title": "Finished!", "body": "If you have any questions feel free to hop on [Gitter](https://gitter.im/trevorsenior/snoocore) and ask!" } [/block]