{"_id":"57bf3166b9333b0e006d4f4a","category":{"_id":"5744b1fb55d65a0e00b436e1","project":"54774d9af3736008009e9e0e","__v":0,"version":"56a0bd9e3697d80d002ac5e7","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-05-24T19:56:43.747Z","from_sync":false,"order":1,"slug":"getting-started","title":"Getting Started"},"parentDoc":null,"project":"54774d9af3736008009e9e0e","__v":0,"user":"56703d17e10ecb0d0004eed8","version":{"_id":"56a0bd9e3697d80d002ac5e7","project":"54774d9af3736008009e9e0e","__v":20,"createdAt":"2016-01-21T11:14:38.131Z","releaseDate":"2016-01-21T11:14:38.131Z","categories":["56a0bd9f3697d80d002ac5e8","56a0bd9f3697d80d002ac5e9","56a0bd9f3697d80d002ac5ea","56a0bd9f3697d80d002ac5eb","56b098a43a5b810d00745e3f","56b098da8f7a4f0d0029dd10","56d5a8ecf612b80b00fb69cd","570989853ab43c0e0072b2d6","571006aa10300c0e007f6133","5735a52431a73b1700887ca0","5744b0529e045c0e00b7a7a2","5744b1d0b56d431700d8a4fb","5744b1fb55d65a0e00b436e1","5744b218f9c7411700ce560e","5744b220f9c7411700ce560f","5744b2259e045c0e00b7a7a7","5744b22cf8b79f0e00de6a2d","5744b23155d65a0e00b436e4","5744b242c758290e00fbc235","5744b2569e045c0e00b7a7a8","5756a3f2bb92962900dafe3d","57ee23e81e42900e0014a42f","581c822c98676e0f00d240ef"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Sockets","version_clean":"1.1.0","version":"1.1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-25T17:56:54.134Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"Chapter Contents:\n1. [Step 1: Opening Your Instance](#step-1-opening-your-instance)\n2. [Step 2: Creating a Connection to your Syncano Instance's API](#step-2-creating-a-connection-to-your-syncano-insta)\n3. [Step 3: Creating a Data Endpoint Socket](#step-3-creating-a-data-endpoint-socket)\n4. [Step 4: Creating News Item Data Objects](#step-4-creating-news-item-data-objects)\n5. [Step 5: Creating a Schedule Socket](#step-5-creating-a-schedule-socket)\n\nThis tutorial will show you how to wire up a basic Hacker News clone with Syncano. You can utilize Syncano to handle the traditional backend functions of your app such as data management, user authentication, schedules, and realtime communication. This tutorial will focus on two key pieces of Syncano functionality: Data Objects and Scripts.\n\nWe already have the front-end for our **<a href=\"http://bit.ly/syncano-news\" target=\"_blank\">Hacker News clone</a>**, so you don't have to worry about designing it. You'll want to keep this tab open since we'll be referring back to it throughout this tutorial. You may notice that it doesn't look very much like Hacker News at this point, but don't worry! We'll be setting it up shortly to work with Syncano.\n[block:html]\n{\n  \"html\": \"<div style=\\\"text-align:center;\\\">\\n  <a href=\\\"http://bit.ly/syncano-news\\\" target=\\\"_blank\\\">\\n    <button class=\\\"mainBtn\\\" style=\\\"background-color:white;border:solid 2px rgb(28,118,213);padding:1.5em;color:rgb(28,118,213);border-radius:0.25em;\\\">\\n      <span style=\\\"font-size:1.75rem;\\\">Open Hacker News Clone</span>\\n    </button>\\n  </a>\\n</div>\"\n}\n[/block]\nYou'll also need to make sure you've signed up with a <a href=\"https://www.syncano.io\" target=\"_blank\">Syncano account</a>. After you've signed up, or if you already have an account, please open <a href=\"https://dashboard.syncano.io/\" target=\"_blank\">your Dashboard</a>.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 1: Opening Your Instance\"\n}\n[/block]\nEverything in Syncano lives in an Instance. You can think of each Instance as a project for your application. One Instance can be used for multiple apps, but we suggest using one Instance per app. You can also use one Instance for let's say both the desktop and mobile versions of your app. \n\nPlease use the images below to locate where you are in the Dashboard, and then open your Instance.\n\nIf you just signed up, your first Instance was created for you. You may already have your Instance open, which will look similar to the image below:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/37f8432-new_open_instance.png\",\n        \"new open instance.png\",\n        1920,\n        983,\n        \"#e8e8e9\"\n      ]\n    }\n  ]\n}\n[/block]\nBut instead if you see the Instance list page as seen below, then open the Instance you want to use for this tutorial:\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/5e81e52-instance-list-cropped.png\",\n        \"instance-list-cropped.png\",\n        1920,\n        520,\n        \"#2d4b7c\"\n      ]\n    }\n  ]\n}\n[/block]\n[//]: # (To create an Instance, simply click the big blue \"Add\" button at the top of the page.)\n\n[//]: # (![add-instance](https://www.syncano.io/blog/content/images/2016/07/add-instance.png))\n\n[//]: # (Then you'll give your Instance a name, a description if you'd like, and select \"Confirm\".)\n\n[//]: # (![create-instance](https://www.syncano.io/blog/content/images/2016/07/Screen-Shot-2016-07-18-at-11-45-37-AM.png))\n\n[//]: # (Congratulations! You've created your first Instance. Click on the Instance name to enter that Instance's Dashboard.)\n\n#### How the Syncano Dashboard Works\n\nThe Dashboard is where you can add different Sockets, or building blocks, to your application. These Sockets can be used as standalone pieces of your app, or they can be combined for even greater functionality.\n\nEverything you create in the Dashboard will be saved as part of your Instance's unique API. From the client-side of your app, you'll be able to interact with your Instance's API through HTTP calls or through your favorite coding language via <a href=\"http://docs.syncano.io/docs/syncano-libraries\" target=\"_blank\">Syncano's many libraries</a>.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 2: Creating a Connection to your Syncano Instance's API\"\n}\n[/block]\nYou'll want to go ahead and connect your Instance with our Hacker News front-end (the link you kept open from the intro). To do this, we need two things:\n\n1. An API Key\n2. Your Instance name\n\n#### Creating an API Key\nWhen making a connection to your Syncano Instance, you'll need an API Key. In this example, we will use an API Key with a special flag that ignores any permissions set on your data. For the purpose of this tutorial, we won't explain how this flag works, but you can read more about [permissions here](doc:authentication).\n\nFirst, open your API Key Manager by click on \"API Keys\" in the lower part of the Dashboard side bar as highlighted in red below:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/bd724db-highlight-api-keys.png\",\n        \"highlight-api-keys.png\",\n        1920,\n        983,\n        \"#e8e8e9\"\n      ]\n    }\n  ]\n}\n[/block]\nThen, create an API Key that matches the following image:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a098314-api_key_creation.png\",\n        \"api key creation.png\",\n        992,\n        707,\n        \"#f7f7f8\"\n      ]\n    }\n  ]\n}\n[/block]\n**Copy the new API Key and save it for later!**\n\n#### Getting your Instance name\nYour Instance Name can be found at the top left corner of your Dashboard. In the screenshot below, it is \"nameless-pine-8974\".\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/fb9359e-highlight-instance-name.png\",\n        \"highlight-instance-name.png\",\n        1920,\n        572,\n        \"#314a78\"\n      ]\n    }\n  ]\n}\n[/block]\nBack in the Hacker News clone, select \"Link Account\" from the top menu. Paste your API Key and Instance name in the spaces provided and hit \"Submit\". If the link is successful, you should see the \"Account successfully linked!\" message.\n\n![link-account](https://www.syncano.io/blog/content/images/2016/08/Screen-Shot-2016-08-18-at-9-41-03-AM.png)\n\nNext, we'll set up a Data Endpoint and some Data Objects for the News Items that we'll be displaying on this page.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 3: Creating a Data Endpoint Socket\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"A Data Endpoint Socket is a customized endpoint that you can make a request to which will allow you to retrieve your data!\\n\\nIt will return your data with any of the custom filters or in the specific order that you set on the configuration of the Socket. <a href=\\\"http://docs.syncano.io/docs/endpoints-data\\\" target=\\\"_blank\\\">Learn more about Data Endpoint Sockets</a>\",\n  \"title\": \"Data Endpoint Socket\"\n}\n[/block]\nOur Hacker News clone wouldn't be complete without allowing users to upload and upvote interesting links they find from around the Internet. We'll call these `News Items` and we'll need to set up a Data Endpoint for them in our app.\n\nTo do this, we'll navigate back to the Syncano Dashboard and create a new Data Endpoint. First, click `ADD` in the top right corner, or next to the Data Endpoint box as seen below:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3d88b5b-Add-Button-Screen.png\",\n        \"Add-Button-Screen.png\",\n        1920,\n        364,\n        \"#304a78\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f624ba8-Add-Data-Endpoint.png\",\n        \"Add-Data-Endpoint.png\",\n        1920,\n        625,\n        \"#304b78\"\n      ]\n    }\n  ]\n}\n[/block]\nWe're going to name our Data Endpoint `get_news_items` simply because it's going to do just that! It will get our news items and send it to our app as a nicely formatted JSON when we make a request to it. The great thing about creating a Data Endpoint is that you can create a Class right inside the creation screen. We'll get into what a Class is in a second, but for now fill out Step 1 of the Data Endpoint creation like this:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0a77d3e-Data_Endpoint_Step_1.png\",\n        \"Data Endpoint Step 1.png\",\n        1035,\n        575,\n        \"#2d70a8\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"What is a Class?\",\n  \"body\": \"A Class is a template for data objects you will be storing in Syncano. In order to be able to add Data Objects, you have to define a Class for that type of data object. In this example, the Class will define the template for each `news item`.\\n<a href=\\\"http://docs.syncano.io/docs/classes-overview\\\" target=\\\"_blank\\\">You can learn more about Classes here.</a>\"\n}\n[/block]\nThe next screen you're going to see is a Class creation screen. This is where you'll define the template for each individual `news item`.\n\nYou'll want a `title` field that is of type `string` so that each data object can have the name of the article, a `url` field also of type `string` to store the articles URL, and an `upvotes` field that is of type integer so we can measure the amount of upvotes each `news item` has.\n\nYou'll also notice that we checked the \"Order\" box on the upvotes field. This is so we can `get` our data sorted by upvotes, sending the `news item` with the highest amount of upvotes to the top.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/d6a8750-Data_Endpoint_Step_2_-_Class.png\",\n        \"Data Endpoint Step 2 - Class.png\",\n        1011,\n        946,\n        \"#f6f7f7\"\n      ]\n    }\n  ]\n}\n[/block]\nThe last step is to configure the specific fields that will be retrieved when making a request. We can choose to only see one field, all of the fields, or anywhere in between. We can also choose how many, the order in which they are sorted, and any other specific query in case you want to for example see only a specific date range!\n\nMake sure yours matches the image below:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f1b3303-Data-Endpoint-Step-3.png\",\n        \"Data-Endpoint-Step-3.png\",\n        1058,\n        864,\n        \"#ececec\"\n      ]\n    }\n  ]\n}\n[/block]\nThat's it! You're Data Endpoint is configured. As long as you entered your API Key and Instance information as mentioned above, you're all set!\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 4: Creating News Item Data Objects\"\n}\n[/block]\n\nNow that we have our Class set up through creating our Data Endpoint, we need to add Data Objects. There are a couple of ways to do this.\n\nOne way is to add them directly from the Syncano Dashboard by clicking on the blue box in the Data Objects column of the Class you want, then adding Data Objects by selecting the \"+\" button at the top.\n\nOr, like in our case here, you can use the API to allow users to be able to create news items directly from our Hacker News app. Luckily, our app is already wired up to create news items when the \"Add a News Item\" form is submitted.\n\nIf you connected the app to your Syncano Instance correctly, you should be able to create news items and they will appear on the screen.\n\n![create-news-item](https://www.syncano.io/blog/content/images/2016/07/Screen-Shot-2016-07-18-at-4-17-08-PM.png)\n\nYou can also upvote news items and the order will change based on what news items have the most votes.\n\nThis form makes calls to the Syncano API to create new Data Objects when the form is submitted. It also increments each news item's `upvotes` property when the up arrow is clicked.\n\nBehind the scenes, the app is accessing the Syncano API through the JavaScript library. You can learn more about the JavaScript library [here](http://docs.syncano.io/docs/javascript).\n\nThis is a basic example of data management with Syncano. Class properties are very customizable, so you can add any fields you deem necessary to your future Classes!\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 5: Creating a Schedule Socket\"\n}\n[/block]\nNow that we have our data, let's add a new feature to this app. What if we wanted to \"review\" and delete news items that didn't have any upvotes each day?\n\nTo do this, we're going to create a Schedule Socket. This Socket will run a specific Script at the interval or schedule you set. Scripts are snippets of code that can be run to perform custom functions in Syncano. These custom functions can be anything your creative brain can think of and are a great way to interface with third-party API's.\n\nScripts can currently be written in Node, Go, PHP, Python, Ruby, and Swift. If you know any third-party API libraries that utilize one of these runtimes, you can include them directly in your Script just like you would normally. Most common API's are supported, but if the one you want to use isn't, simply make a request on <a href=\"https://github.com/Syncano\" target=\"_blank\">GitHub</a> or via the blue \"?\" at the bottom of the Dashboard to add it.\n\nIn our case, we want to write a Schedule Socket that will check our news items and delete those with no upvotes on a daily basis - let's say 12am UTC.\n\nFirst, let's go back to our Sockets page so we can add a Schedule Socket.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2ee7d33-Add-Button-Screen.png\",\n        \"Add-Button-Screen.png\",\n        1920,\n        364,\n        \"#304a78\"\n      ]\n    }\n  ]\n}\n[/block]\nThen click `ADD` in the Schedule Socket box.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8353bbf-Add-Schedule-Socket.png\",\n        \"Add-Schedule-Socket.png\",\n        838,\n        648,\n        \"#cbd3cf\"\n      ]\n    }\n  ]\n}\n[/block]\nThe next screen you'll see is where you fill out the details for the Schedule. Create a Script called `clean_up` by typing that name in the \"Script\" input field. Then set the Crontab, which tells the Schedule Socket how often it should run, to \"Run once a day at midnight\" or `0 0 * * *`. Lastly, set the timezone to UTC (you can also pick your timezone if you'd like).\n\nMake sure it all looks like this:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/cb375b2-Schedule-Step-1.png\",\n        \"Schedule-Step-1.png\",\n        1055,\n        840,\n        \"#f5f5f5\"\n      ]\n    }\n  ]\n}\n[/block]\nNext it will open the Script creation screen, which you will fill out as follows:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/639fd9e-Schedule-Step-2-Script.png\",\n        \"Schedule-Step-2-Script.png\",\n        1006,\n        731,\n        \"#f5f5f5\"\n      ]\n    }\n  ]\n}\n[/block]\nCongrats! You've done it. Now we're going to open this Script so we can add the code (otherwise your schedule will run and nothing will happen!)\n\n### Editing the Script\n\nAssuming you haven't left the Sockets page yet, click on the link in the \"Script\" column of your new Schedule Socket labeled `clean_up` to open that Script. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b63344d-Schedule-Row.png\",\n        \"Schedule-Row.png\",\n        1629,\n        160,\n        \"#e1e4e0\"\n      ]\n    }\n  ]\n}\n[/block]\nThis is a just a shortcut - you could instead click \"Scripts\" under \"Snippets\" using the left side-bar, and then click on `clean_up`. Your screen should now look something like this:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/2abc07f-new-script-cropped.png\",\n        \"new-script-cropped.png\",\n        1920,\n        796,\n        \"#2e4b7a\"\n      ]\n    }\n  ]\n}\n[/block]\nOn this screen, you can enter code into the code editor. For our Script, we'll enter the following code.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var Syncano = require('syncano'); // import Syncano JS Library\\nvar connection = Syncano({ // set up API connection\\n    apiKey: CONFIG.apiKey,\\n    defaults: {instanceName: META.instance} // the Instance this Script is in\\n});\\nvar className = CONFIG.className; // setting the class name\\n\\n// List all of the objects in your Class\\nconnection.DataObject.please().list({className: className})\\n  .then(function(items) {\\n    items.forEach(function(item) {\\n      if (item.upvotes === 0) { // if no upvotes, delete object\\n        var itemToDelete = {\\n          id: item.id,\\n          className: className\\n        };\\n        // then delete the item through the API\\n        connection.DataObject.please().delete(itemToDelete).then(function(){\\n          console.log(\\\"Item successfully deleted\\\"); \\n        });\\n      }\\n    });\\n\\t});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nThis Script calls Syncano using the JavaScript library. It pulls the list of news items and checks for the ones with no upvotes. It then deletes those news items.\n\nBefore we can run this Script, we just need to add values to a few config variables. This can be done on the right hand side of the code editor where it says \"Config\":\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/c33b5ee-filled_config.png\",\n        \"filled config.png\",\n        534,\n        607,\n        \"#f0f0f0\"\n      ]\n    }\n  ]\n}\n[/block]\nAny config variable you add can be accessed in your code. For example, in NodeJS you can use the `CONFIG.keyName` syntax as seen in the code above. <a href=\"http://docs.syncano.io/docs/snippets-scripts#scripts-data-dictionaries-args-config-global-confi\" target=\"_blank\">Read more about CONFIG here</a>.\n\nWe'll need config variables for `apiKey` and `className` to get this Script to run properly.\n\nThe `apiKey` config will be the same API Key we used earlier we used earlier, and `className` should be set to `news_item`.\n\nOnce we have everything configured properly, let's test the Script. Go back to your `news_item` Class and create a new Data Object. Give it the title `should delete` and make sure it has 0 upvotes.\n\nReturn back to the Hacker News tab to make sure your `should delete` news item is there.\n\nNow, go to the Script we just wrote and configured and click \"Run\". The Script should run without any errors. Go back to the Hacker News app and the `should delete` news item should no longer be there!\n\nSince we set up the Schedule Socket, everyday at 12am UTC this Script will run and delete any `news items` that have zero upvotes.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What's Next?\"\n}\n[/block]\nThere are an infinite amount of things you could do next with the Syncano. Here are a couple suggestions!\n\n#### Even More Sockets!\nSockets, as we mentioned in this guide, are your building blocks on Syncano. There are many things you can do with them like schedule tasks, trigger Scripts based on data changes, delivery real time data updates and Push Notifications to your users, and more! [Read more about Sockets here](http://docs.syncano.io/docs/syncano-what-are-sockets).\n\n#### Example Apps\n[Here you will find a bunch of Example Apps](http://docs.syncano.io/docs/example-apps) that you can build on Syncano. They will help you understand how to use more features of the platform, as well as show you how to use our various Libraries and SDKs.","excerpt":"This Syncano Quick Start tutorial will show you how to wire up a basic Hacker News clone","slug":"quick-start-tutorial","type":"basic","title":"Quick Start Tutorial"}

Quick Start Tutorial

This Syncano Quick Start tutorial will show you how to wire up a basic Hacker News clone

Chapter Contents: 1. [Step 1: Opening Your Instance](#step-1-opening-your-instance) 2. [Step 2: Creating a Connection to your Syncano Instance's API](#step-2-creating-a-connection-to-your-syncano-insta) 3. [Step 3: Creating a Data Endpoint Socket](#step-3-creating-a-data-endpoint-socket) 4. [Step 4: Creating News Item Data Objects](#step-4-creating-news-item-data-objects) 5. [Step 5: Creating a Schedule Socket](#step-5-creating-a-schedule-socket) This tutorial will show you how to wire up a basic Hacker News clone with Syncano. You can utilize Syncano to handle the traditional backend functions of your app such as data management, user authentication, schedules, and realtime communication. This tutorial will focus on two key pieces of Syncano functionality: Data Objects and Scripts. We already have the front-end for our **<a href="http://bit.ly/syncano-news" target="_blank">Hacker News clone</a>**, so you don't have to worry about designing it. You'll want to keep this tab open since we'll be referring back to it throughout this tutorial. You may notice that it doesn't look very much like Hacker News at this point, but don't worry! We'll be setting it up shortly to work with Syncano. [block:html] { "html": "<div style=\"text-align:center;\">\n <a href=\"http://bit.ly/syncano-news\" target=\"_blank\">\n <button class=\"mainBtn\" style=\"background-color:white;border:solid 2px rgb(28,118,213);padding:1.5em;color:rgb(28,118,213);border-radius:0.25em;\">\n <span style=\"font-size:1.75rem;\">Open Hacker News Clone</span>\n </button>\n </a>\n</div>" } [/block] You'll also need to make sure you've signed up with a <a href="https://www.syncano.io" target="_blank">Syncano account</a>. After you've signed up, or if you already have an account, please open <a href="https://dashboard.syncano.io/" target="_blank">your Dashboard</a>. [block:api-header] { "type": "basic", "title": "Step 1: Opening Your Instance" } [/block] Everything in Syncano lives in an Instance. You can think of each Instance as a project for your application. One Instance can be used for multiple apps, but we suggest using one Instance per app. You can also use one Instance for let's say both the desktop and mobile versions of your app. Please use the images below to locate where you are in the Dashboard, and then open your Instance. If you just signed up, your first Instance was created for you. You may already have your Instance open, which will look similar to the image below: [block:image] { "images": [ { "image": [ "https://files.readme.io/37f8432-new_open_instance.png", "new open instance.png", 1920, 983, "#e8e8e9" ] } ] } [/block] But instead if you see the Instance list page as seen below, then open the Instance you want to use for this tutorial: [block:image] { "images": [ { "image": [ "https://files.readme.io/5e81e52-instance-list-cropped.png", "instance-list-cropped.png", 1920, 520, "#2d4b7c" ] } ] } [/block] [//]: # (To create an Instance, simply click the big blue "Add" button at the top of the page.) [//]: # (![add-instance](https://www.syncano.io/blog/content/images/2016/07/add-instance.png)) [//]: # (Then you'll give your Instance a name, a description if you'd like, and select "Confirm".) [//]: # (![create-instance](https://www.syncano.io/blog/content/images/2016/07/Screen-Shot-2016-07-18-at-11-45-37-AM.png)) [//]: # (Congratulations! You've created your first Instance. Click on the Instance name to enter that Instance's Dashboard.) #### How the Syncano Dashboard Works The Dashboard is where you can add different Sockets, or building blocks, to your application. These Sockets can be used as standalone pieces of your app, or they can be combined for even greater functionality. Everything you create in the Dashboard will be saved as part of your Instance's unique API. From the client-side of your app, you'll be able to interact with your Instance's API through HTTP calls or through your favorite coding language via <a href="http://docs.syncano.io/docs/syncano-libraries" target="_blank">Syncano's many libraries</a>. [block:api-header] { "type": "basic", "title": "Step 2: Creating a Connection to your Syncano Instance's API" } [/block] You'll want to go ahead and connect your Instance with our Hacker News front-end (the link you kept open from the intro). To do this, we need two things: 1. An API Key 2. Your Instance name #### Creating an API Key When making a connection to your Syncano Instance, you'll need an API Key. In this example, we will use an API Key with a special flag that ignores any permissions set on your data. For the purpose of this tutorial, we won't explain how this flag works, but you can read more about [permissions here](doc:authentication). First, open your API Key Manager by click on "API Keys" in the lower part of the Dashboard side bar as highlighted in red below: [block:image] { "images": [ { "image": [ "https://files.readme.io/bd724db-highlight-api-keys.png", "highlight-api-keys.png", 1920, 983, "#e8e8e9" ] } ] } [/block] Then, create an API Key that matches the following image: [block:image] { "images": [ { "image": [ "https://files.readme.io/a098314-api_key_creation.png", "api key creation.png", 992, 707, "#f7f7f8" ] } ] } [/block] **Copy the new API Key and save it for later!** #### Getting your Instance name Your Instance Name can be found at the top left corner of your Dashboard. In the screenshot below, it is "nameless-pine-8974". [block:image] { "images": [ { "image": [ "https://files.readme.io/fb9359e-highlight-instance-name.png", "highlight-instance-name.png", 1920, 572, "#314a78" ] } ] } [/block] Back in the Hacker News clone, select "Link Account" from the top menu. Paste your API Key and Instance name in the spaces provided and hit "Submit". If the link is successful, you should see the "Account successfully linked!" message. ![link-account](https://www.syncano.io/blog/content/images/2016/08/Screen-Shot-2016-08-18-at-9-41-03-AM.png) Next, we'll set up a Data Endpoint and some Data Objects for the News Items that we'll be displaying on this page. [block:api-header] { "type": "basic", "title": "Step 3: Creating a Data Endpoint Socket" } [/block] [block:callout] { "type": "info", "body": "A Data Endpoint Socket is a customized endpoint that you can make a request to which will allow you to retrieve your data!\n\nIt will return your data with any of the custom filters or in the specific order that you set on the configuration of the Socket. <a href=\"http://docs.syncano.io/docs/endpoints-data\" target=\"_blank\">Learn more about Data Endpoint Sockets</a>", "title": "Data Endpoint Socket" } [/block] Our Hacker News clone wouldn't be complete without allowing users to upload and upvote interesting links they find from around the Internet. We'll call these `News Items` and we'll need to set up a Data Endpoint for them in our app. To do this, we'll navigate back to the Syncano Dashboard and create a new Data Endpoint. First, click `ADD` in the top right corner, or next to the Data Endpoint box as seen below: [block:image] { "images": [ { "image": [ "https://files.readme.io/3d88b5b-Add-Button-Screen.png", "Add-Button-Screen.png", 1920, 364, "#304a78" ] } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/f624ba8-Add-Data-Endpoint.png", "Add-Data-Endpoint.png", 1920, 625, "#304b78" ] } ] } [/block] We're going to name our Data Endpoint `get_news_items` simply because it's going to do just that! It will get our news items and send it to our app as a nicely formatted JSON when we make a request to it. The great thing about creating a Data Endpoint is that you can create a Class right inside the creation screen. We'll get into what a Class is in a second, but for now fill out Step 1 of the Data Endpoint creation like this: [block:image] { "images": [ { "image": [ "https://files.readme.io/0a77d3e-Data_Endpoint_Step_1.png", "Data Endpoint Step 1.png", 1035, 575, "#2d70a8" ] } ] } [/block] [block:callout] { "type": "info", "title": "What is a Class?", "body": "A Class is a template for data objects you will be storing in Syncano. In order to be able to add Data Objects, you have to define a Class for that type of data object. In this example, the Class will define the template for each `news item`.\n<a href=\"http://docs.syncano.io/docs/classes-overview\" target=\"_blank\">You can learn more about Classes here.</a>" } [/block] The next screen you're going to see is a Class creation screen. This is where you'll define the template for each individual `news item`. You'll want a `title` field that is of type `string` so that each data object can have the name of the article, a `url` field also of type `string` to store the articles URL, and an `upvotes` field that is of type integer so we can measure the amount of upvotes each `news item` has. You'll also notice that we checked the "Order" box on the upvotes field. This is so we can `get` our data sorted by upvotes, sending the `news item` with the highest amount of upvotes to the top. [block:image] { "images": [ { "image": [ "https://files.readme.io/d6a8750-Data_Endpoint_Step_2_-_Class.png", "Data Endpoint Step 2 - Class.png", 1011, 946, "#f6f7f7" ] } ] } [/block] The last step is to configure the specific fields that will be retrieved when making a request. We can choose to only see one field, all of the fields, or anywhere in between. We can also choose how many, the order in which they are sorted, and any other specific query in case you want to for example see only a specific date range! Make sure yours matches the image below: [block:image] { "images": [ { "image": [ "https://files.readme.io/f1b3303-Data-Endpoint-Step-3.png", "Data-Endpoint-Step-3.png", 1058, 864, "#ececec" ] } ] } [/block] That's it! You're Data Endpoint is configured. As long as you entered your API Key and Instance information as mentioned above, you're all set! [block:api-header] { "type": "basic", "title": "Step 4: Creating News Item Data Objects" } [/block] Now that we have our Class set up through creating our Data Endpoint, we need to add Data Objects. There are a couple of ways to do this. One way is to add them directly from the Syncano Dashboard by clicking on the blue box in the Data Objects column of the Class you want, then adding Data Objects by selecting the "+" button at the top. Or, like in our case here, you can use the API to allow users to be able to create news items directly from our Hacker News app. Luckily, our app is already wired up to create news items when the "Add a News Item" form is submitted. If you connected the app to your Syncano Instance correctly, you should be able to create news items and they will appear on the screen. ![create-news-item](https://www.syncano.io/blog/content/images/2016/07/Screen-Shot-2016-07-18-at-4-17-08-PM.png) You can also upvote news items and the order will change based on what news items have the most votes. This form makes calls to the Syncano API to create new Data Objects when the form is submitted. It also increments each news item's `upvotes` property when the up arrow is clicked. Behind the scenes, the app is accessing the Syncano API through the JavaScript library. You can learn more about the JavaScript library [here](http://docs.syncano.io/docs/javascript). This is a basic example of data management with Syncano. Class properties are very customizable, so you can add any fields you deem necessary to your future Classes! [block:api-header] { "type": "basic", "title": "Step 5: Creating a Schedule Socket" } [/block] Now that we have our data, let's add a new feature to this app. What if we wanted to "review" and delete news items that didn't have any upvotes each day? To do this, we're going to create a Schedule Socket. This Socket will run a specific Script at the interval or schedule you set. Scripts are snippets of code that can be run to perform custom functions in Syncano. These custom functions can be anything your creative brain can think of and are a great way to interface with third-party API's. Scripts can currently be written in Node, Go, PHP, Python, Ruby, and Swift. If you know any third-party API libraries that utilize one of these runtimes, you can include them directly in your Script just like you would normally. Most common API's are supported, but if the one you want to use isn't, simply make a request on <a href="https://github.com/Syncano" target="_blank">GitHub</a> or via the blue "?" at the bottom of the Dashboard to add it. In our case, we want to write a Schedule Socket that will check our news items and delete those with no upvotes on a daily basis - let's say 12am UTC. First, let's go back to our Sockets page so we can add a Schedule Socket. [block:image] { "images": [ { "image": [ "https://files.readme.io/2ee7d33-Add-Button-Screen.png", "Add-Button-Screen.png", 1920, 364, "#304a78" ] } ] } [/block] Then click `ADD` in the Schedule Socket box. [block:image] { "images": [ { "image": [ "https://files.readme.io/8353bbf-Add-Schedule-Socket.png", "Add-Schedule-Socket.png", 838, 648, "#cbd3cf" ] } ] } [/block] The next screen you'll see is where you fill out the details for the Schedule. Create a Script called `clean_up` by typing that name in the "Script" input field. Then set the Crontab, which tells the Schedule Socket how often it should run, to "Run once a day at midnight" or `0 0 * * *`. Lastly, set the timezone to UTC (you can also pick your timezone if you'd like). Make sure it all looks like this: [block:image] { "images": [ { "image": [ "https://files.readme.io/cb375b2-Schedule-Step-1.png", "Schedule-Step-1.png", 1055, 840, "#f5f5f5" ] } ] } [/block] Next it will open the Script creation screen, which you will fill out as follows: [block:image] { "images": [ { "image": [ "https://files.readme.io/639fd9e-Schedule-Step-2-Script.png", "Schedule-Step-2-Script.png", 1006, 731, "#f5f5f5" ] } ] } [/block] Congrats! You've done it. Now we're going to open this Script so we can add the code (otherwise your schedule will run and nothing will happen!) ### Editing the Script Assuming you haven't left the Sockets page yet, click on the link in the "Script" column of your new Schedule Socket labeled `clean_up` to open that Script. [block:image] { "images": [ { "image": [ "https://files.readme.io/b63344d-Schedule-Row.png", "Schedule-Row.png", 1629, 160, "#e1e4e0" ] } ] } [/block] This is a just a shortcut - you could instead click "Scripts" under "Snippets" using the left side-bar, and then click on `clean_up`. Your screen should now look something like this: [block:image] { "images": [ { "image": [ "https://files.readme.io/2abc07f-new-script-cropped.png", "new-script-cropped.png", 1920, 796, "#2e4b7a" ] } ] } [/block] On this screen, you can enter code into the code editor. For our Script, we'll enter the following code. [block:code] { "codes": [ { "code": "var Syncano = require('syncano'); // import Syncano JS Library\nvar connection = Syncano({ // set up API connection\n apiKey: CONFIG.apiKey,\n defaults: {instanceName: META.instance} // the Instance this Script is in\n});\nvar className = CONFIG.className; // setting the class name\n\n// List all of the objects in your Class\nconnection.DataObject.please().list({className: className})\n .then(function(items) {\n items.forEach(function(item) {\n if (item.upvotes === 0) { // if no upvotes, delete object\n var itemToDelete = {\n id: item.id,\n className: className\n };\n // then delete the item through the API\n connection.DataObject.please().delete(itemToDelete).then(function(){\n console.log(\"Item successfully deleted\"); \n });\n }\n });\n\t});", "language": "javascript" } ] } [/block] This Script calls Syncano using the JavaScript library. It pulls the list of news items and checks for the ones with no upvotes. It then deletes those news items. Before we can run this Script, we just need to add values to a few config variables. This can be done on the right hand side of the code editor where it says "Config": [block:image] { "images": [ { "image": [ "https://files.readme.io/c33b5ee-filled_config.png", "filled config.png", 534, 607, "#f0f0f0" ] } ] } [/block] Any config variable you add can be accessed in your code. For example, in NodeJS you can use the `CONFIG.keyName` syntax as seen in the code above. <a href="http://docs.syncano.io/docs/snippets-scripts#scripts-data-dictionaries-args-config-global-confi" target="_blank">Read more about CONFIG here</a>. We'll need config variables for `apiKey` and `className` to get this Script to run properly. The `apiKey` config will be the same API Key we used earlier we used earlier, and `className` should be set to `news_item`. Once we have everything configured properly, let's test the Script. Go back to your `news_item` Class and create a new Data Object. Give it the title `should delete` and make sure it has 0 upvotes. Return back to the Hacker News tab to make sure your `should delete` news item is there. Now, go to the Script we just wrote and configured and click "Run". The Script should run without any errors. Go back to the Hacker News app and the `should delete` news item should no longer be there! Since we set up the Schedule Socket, everyday at 12am UTC this Script will run and delete any `news items` that have zero upvotes. [block:api-header] { "type": "basic", "title": "What's Next?" } [/block] There are an infinite amount of things you could do next with the Syncano. Here are a couple suggestions! #### Even More Sockets! Sockets, as we mentioned in this guide, are your building blocks on Syncano. There are many things you can do with them like schedule tasks, trigger Scripts based on data changes, delivery real time data updates and Push Notifications to your users, and more! [Read more about Sockets here](http://docs.syncano.io/docs/syncano-what-are-sockets). #### Example Apps [Here you will find a bunch of Example Apps](http://docs.syncano.io/docs/example-apps) that you can build on Syncano. They will help you understand how to use more features of the platform, as well as show you how to use our various Libraries and SDKs.