{"_id":"563a2dbc1846790d0089530f","project":"54d4ecb5f6c48a0d00f0f041","user":"54d4ec36f6c48a0d00f0f040","version":{"_id":"563a2dba1846790d00895309","__v":3,"project":"54d4ecb5f6c48a0d00f0f041","createdAt":"2015-11-04T16:09:30.844Z","releaseDate":"2015-11-04T16:09:30.844Z","categories":["563a2dbb1846790d0089530a","563a2dbb1846790d0089530b","563a2dbb1846790d0089530c","56620e60f183880d004d3217","5702e5b8f2d6f336005e9025"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"No Mashape","version_clean":"1.1.0","version":"1.1"},"category":{"_id":"563a2dbb1846790d0089530a","__v":3,"pages":["563a2dbc1846790d0089530f","563a2dbc1846790d00895310","563a2dbc1846790d00895311","563a2dbc1846790d00895312","563a2dbc1846790d00895313","563a2dbc1846790d00895314","563a2dbc1846790d00895315","563a2dbc1846790d00895316","563a2dbc1846790d00895317","566232310299ea0d008f2cf2","56623a2d0299ea0d008f2cf6"],"project":"54d4ecb5f6c48a0d00f0f041","version":"563a2dba1846790d00895309","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-02-06T16:32:54.503Z","from_sync":false,"order":2,"slug":"documentation","title":"Documentation"},"__v":21,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-02-06T16:32:55.239Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"This ***Getting Started*** guide will help you make your first calls to the Instacount API.   Once completed, you will be able to increment a counter in the API and get its current count.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 1: Subscribe to an Instacount Plan\"\n}\n[/block]\nTo get started, you'll need to subscribe to one of the Instacount API plans found on our <a href=\"https://www.instacount.io/pricing.html\" target=\"_blank\">pricing page</a> page.\n\nIf you're not ready to commit to a subscription, choose our **Free Plan**.  It's quite limited, but should give you enough quota to test things out.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"If You Need Billing Help\",\n  \"body\": \"If you need any assistance getting subscribed to a plan, or any other payment-related help, just email us at [success:::at:::instacount.io](mailto:success@instacount.io).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 2: Sign-in to the Instacount Dashboard\"\n}\n[/block]\nThe Instacount dashboard is your central place to view and manage all of your counter data.  To get started, navigate to the <a href=\"https://www.instacount.io/dashboard/\" target=\"_blank\">dashboard</a> and sign-in*. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Instacount Dashboard\",\n  \"body\": \"For reference, the URL of the Instacount Dashboard is:\\n\\n<b><a href=\\\"https://www.instacount.io/dashboard/\\\" target=\\\"_blank\\\">https://www.instacount.io/dashboard/</a></b>\"\n}\n[/block]\nFor more detailed information about how the dashboard works, navigate to the documentation section called [Instacount Dashboard](doc:instacount-dashboard).\n\n**Note: The Instacount Dashboard requires a [Google Account](https://accounts.google.com/) to sign-in.* \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 3: Create an Application (Dashboard)\"\n}\n[/block]\nInstacount segments counter data using a concept called ***Applications***.  \n\nYou'll want to create a new application for each app or website that you want to use Instacount on.  For example, you might have a single website that would use an Instacount Application called \"*Production*\" and another one called \"*Testing*.\"\n\nFor purposes of this guide, you can either create a new application in the Dashboard, or simply use the default application called \"*Test Application*\" instead.\n\nWhichever application you choose, you'll want to capture the **Application Id** and the **Read-Write** key.  We'll use them in the next step.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Finding Your Application Keys\",\n  \"body\": \"Application keys can be found on each application in the <a href=\\\"https://www.instacount.io/dashboard/applications.html\\\" target=\\\"_blank\\\">Applications</a> listing page in the Dashboard.  API Keys are hidden by default, so to expose them, click the \\\"*edit application*\\\" icon in the column labelled \\\"*Adjust*.\\\"\"\n}\n[/block]\nAt this point, you have all of the information necessary to call the Instacount API.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Information Required to Call the Instacount API\",\n  \"body\": \"* **Instacount Application Id**\\nThe unique identifier for an application in Instacount (found in the <a href=\\\"https://www.instacount.io/dashboard/\\\" target=\\\"_blank\\\">Instacount Dashboard</a>).\\n\\n* **Instacount Application API Key**\\nThe key used to govern the type of access a caller has to a particular Instacount application (found in the <a href=\\\"https://www.instacount.io/dashboard/\\\" target=\\\"_blank\\\">Instacount Dashboard</a>).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 4: Create a New Counter (Dashboard)\"\n}\n[/block]\nFirst, let's create a new counter by navigating to the [Dashboard](https://www.instacount.io/dashboard/applications.html).  \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/IzGoNIfQTOka3oEjbAXt_counters_page.png\",\n        \"counters_page.png\",\n        \"2836\",\n        \"1226\",\n        \"#fc1421\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nOnce you've signed-in, you'll want to click the **Counters** page link on the left-hand menu.  The screen-shot below shows an example.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/TpS3WKFPQ1KZLejEIwIu_counter_page2.png\",\n        \"counter_page2.png\",\n        \"2842\",\n        \"1220\",\n        \"#5bb86e\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nTo create a counter, click the green **New** button, and fill-in the details in the prompt box.  Here's an example:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/58mq67LzSrrY2XlLmIe6_new_counter.png\",\n        \"new_counter.png\",\n        \"2828\",\n        \"1204\",\n        \"#253f47\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nClick Save, and your new counter will be ready to increment.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/VoCNM1kRVyI76pnQkecS_two_counters.png\",\n        \"two_counters.png\",\n        \"2844\",\n        \"1220\",\n        \"#5bb675\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Finding a New Counter's Name\",\n  \"body\": \"When creating a new counter, it's possible to omit the counter name and Instacount will create a globally-unique counter name for you.  After any successful creation of an Instacount counter, the **Location** response header will contain a URL to the newly created counter resource. You can find your new counter's name by performing a GET on this URL and inspecting the **name** attribute in the returned JSON response representation.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Avoid Parsing/Decoding the Location URL\",\n  \"body\": \"The URL returned in the **Location** response header may contain URL-encoded values, and should not be parsed or decoded to obtain specific counter attributes, such as the counter name.  For example, creating a counter named \\\"counter-吧吧\\\" would yield a **Location** header value of https://api.instacount.io/sharded_counters/counter-%E5%90%A7%E5%90%A7.  If you parsed this URL to get the counter name, you would need to URL decode the value before using it.  Instead, prefer retrieving the JSON representation of this counter and then access the **name** field directly.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 5: Increment a Counter (via Dashboard)\"\n}\n[/block]\nNext, let's increment your newly-created counter.  Just click the **plus button** (+) to the right of any counter, and voila!  You've incremented your first counter.  \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7Y5UKR7R8aEis2rb5wIQ_two_counters_with_count.png\",\n        \"two_counters_with_count.png\",\n        \"2842\",\n        \"1210\",\n        \"#5bb672\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Increment/Decrement requests are applied across various counter <a href=\\\"https://en.wikipedia.org/wiki/Shard_(database_architecture)\\\" target=\\\"_blank\\\">shards</a>, so it's not practical to return the current count of a counter after these types of operations.  Instead, to get the real, current count, simply perform an HTTP GET to a counter resource.\",\n  \"title\": \"Determining the True Count of a Counter\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Appendix: cURL Equivalents\"\n}\n[/block]\nYou can always use the Dashboard to make calls to Instacount.  However, sometimes it's easier to test things out on the command line.  The following examples show what you did above, but using cURL.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST --include 'https://api.instacount.io/sharded_counters' \\\\\\n  -H 'Accept: application/vnd.instacount.v1+json' \\\\\\n  -H 'Content-Type: application/vnd.instacount.v1+json' \\\\\\n  -H 'X-Instacount-API-Key: {required, see Instacount Dashboard}' \\\\\\n  -H 'X-Instacount-Application-Id: {required, see Instacount Dashboard}'\",\n      \"language\": \"curl\",\n      \"name\": \"Create a Counter\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"New Counter Names\",\n  \"body\": \"If you create a counter without specifying a **name** attribute, rely on the **Location** response header to obtain a URL to the newly created counter resource. You can find your new counter's name by performing a GET on this URL and inspecting the **name** attribute in the returned JSON response representation.\"\n}\n[/block]\nOnce you've created a counter, you can access its details via the following call.  Be sure to replace the *{counter_name}* value in the request below with the actual name of the counter you created above.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\\\\n-H 'Accept: application/vnd.instacount.v1+json' \\\\\\n-H 'X-Instacount-API-Key: {required, see Instacount Dashboard}' \\\\\\n-H 'X-Instacount-Application-Id: {required, see Instacount Dashboard}' \\\\\\n 'https://api.instacount.io/sharded_counters/{counter_name}' \",\n      \"language\": \"curl\",\n      \"name\": \"Get a Counter by Name\"\n    }\n  ]\n}\n[/block]\nFinally, here's how to increment your counter:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\\\\n -H \\\"Accept: application/vnd.instacount.v1+json\\\" \\\\\\n -H \\\"Content-Type: application/vnd.instacount.v1+json\\\" \\\\\\n -H \\\"X-Instacount-API-Key: {required, see Instacount Dashboard}\\\" \\\\\\n -H \\\"X-Instacount-Application-Id: {required, see Instacount Dashboard}\\\" \\\\\\n -d '{ \\\"amount\\\": 1, \\\"async\\\": false }'\\\\\\n  'http://localhost:8081/sharded_counters/{counter_name}/increments'\",\n      \"language\": \"curl\",\n      \"name\": \"Increment a Counter\"\n    }\n  ]\n}\n[/block]\nAnd, here's how to decrement your counter:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\\\\n -H \\\"Accept: application/vnd.instacount.v1+json\\\" \\\\\\n -H \\\"Content-Type: application/vnd.instacount.v1+json\\\" \\\\\\n -H \\\"X-Instacount-API-Key: <required, see Instacount Dashboard>\\\" \\\\\\n -H \\\"X-Instacount-Application-Id: <required, see Instacount Dashboard>\\\" \\\\\\n -d '{ \\\"amount\\\": 1, \\\"async\\\": false }'\\\\\\n  'http://localhost:8081/sharded_counters/{counter_name}/decrements'\",\n      \"language\": \"curl\",\n      \"name\": \"Decrement a Counter\"\n    }\n  ]\n}\n[/block]","excerpt":"Get started with Instacount using this guide.","slug":"getting-started","type":"basic","title":"Getting Started"}

Getting Started

Get started with Instacount using this guide.

This ***Getting Started*** guide will help you make your first calls to the Instacount API. Once completed, you will be able to increment a counter in the API and get its current count. [block:api-header] { "type": "basic", "title": "Step 1: Subscribe to an Instacount Plan" } [/block] To get started, you'll need to subscribe to one of the Instacount API plans found on our <a href="https://www.instacount.io/pricing.html" target="_blank">pricing page</a> page. If you're not ready to commit to a subscription, choose our **Free Plan**. It's quite limited, but should give you enough quota to test things out. [block:callout] { "type": "success", "title": "If You Need Billing Help", "body": "If you need any assistance getting subscribed to a plan, or any other payment-related help, just email us at [success@instacount.io](mailto:success@instacount.io)." } [/block] [block:api-header] { "type": "basic", "title": "Step 2: Sign-in to the Instacount Dashboard" } [/block] The Instacount dashboard is your central place to view and manage all of your counter data. To get started, navigate to the <a href="https://www.instacount.io/dashboard/" target="_blank">dashboard</a> and sign-in*. [block:callout] { "type": "info", "title": "Instacount Dashboard", "body": "For reference, the URL of the Instacount Dashboard is:\n\n<b><a href=\"https://www.instacount.io/dashboard/\" target=\"_blank\">https://www.instacount.io/dashboard/</a></b>" } [/block] For more detailed information about how the dashboard works, navigate to the documentation section called [Instacount Dashboard](doc:instacount-dashboard). **Note: The Instacount Dashboard requires a [Google Account](https://accounts.google.com/) to sign-in.* [block:api-header] { "type": "basic", "title": "Step 3: Create an Application (Dashboard)" } [/block] Instacount segments counter data using a concept called ***Applications***. You'll want to create a new application for each app or website that you want to use Instacount on. For example, you might have a single website that would use an Instacount Application called "*Production*" and another one called "*Testing*." For purposes of this guide, you can either create a new application in the Dashboard, or simply use the default application called "*Test Application*" instead. Whichever application you choose, you'll want to capture the **Application Id** and the **Read-Write** key. We'll use them in the next step. [block:callout] { "type": "info", "title": "Finding Your Application Keys", "body": "Application keys can be found on each application in the <a href=\"https://www.instacount.io/dashboard/applications.html\" target=\"_blank\">Applications</a> listing page in the Dashboard. API Keys are hidden by default, so to expose them, click the \"*edit application*\" icon in the column labelled \"*Adjust*.\"" } [/block] At this point, you have all of the information necessary to call the Instacount API. [block:callout] { "type": "success", "title": "Information Required to Call the Instacount API", "body": "* **Instacount Application Id**\nThe unique identifier for an application in Instacount (found in the <a href=\"https://www.instacount.io/dashboard/\" target=\"_blank\">Instacount Dashboard</a>).\n\n* **Instacount Application API Key**\nThe key used to govern the type of access a caller has to a particular Instacount application (found in the <a href=\"https://www.instacount.io/dashboard/\" target=\"_blank\">Instacount Dashboard</a>)." } [/block] [block:api-header] { "type": "basic", "title": "Step 4: Create a New Counter (Dashboard)" } [/block] First, let's create a new counter by navigating to the [Dashboard](https://www.instacount.io/dashboard/applications.html). [block:image] { "images": [ { "image": [ "https://files.readme.io/IzGoNIfQTOka3oEjbAXt_counters_page.png", "counters_page.png", "2836", "1226", "#fc1421", "" ] } ] } [/block] Once you've signed-in, you'll want to click the **Counters** page link on the left-hand menu. The screen-shot below shows an example. [block:image] { "images": [ { "image": [ "https://files.readme.io/TpS3WKFPQ1KZLejEIwIu_counter_page2.png", "counter_page2.png", "2842", "1220", "#5bb86e", "" ] } ] } [/block] To create a counter, click the green **New** button, and fill-in the details in the prompt box. Here's an example: [block:image] { "images": [ { "image": [ "https://files.readme.io/58mq67LzSrrY2XlLmIe6_new_counter.png", "new_counter.png", "2828", "1204", "#253f47", "" ] } ] } [/block] Click Save, and your new counter will be ready to increment. [block:image] { "images": [ { "image": [ "https://files.readme.io/VoCNM1kRVyI76pnQkecS_two_counters.png", "two_counters.png", "2844", "1220", "#5bb675", "" ] } ] } [/block] [block:callout] { "type": "info", "title": "Finding a New Counter's Name", "body": "When creating a new counter, it's possible to omit the counter name and Instacount will create a globally-unique counter name for you. After any successful creation of an Instacount counter, the **Location** response header will contain a URL to the newly created counter resource. You can find your new counter's name by performing a GET on this URL and inspecting the **name** attribute in the returned JSON response representation." } [/block] [block:callout] { "type": "danger", "title": "Avoid Parsing/Decoding the Location URL", "body": "The URL returned in the **Location** response header may contain URL-encoded values, and should not be parsed or decoded to obtain specific counter attributes, such as the counter name. For example, creating a counter named \"counter-吧吧\" would yield a **Location** header value of https://api.instacount.io/sharded_counters/counter-%E5%90%A7%E5%90%A7. If you parsed this URL to get the counter name, you would need to URL decode the value before using it. Instead, prefer retrieving the JSON representation of this counter and then access the **name** field directly." } [/block] [block:api-header] { "type": "basic", "title": "Step 5: Increment a Counter (via Dashboard)" } [/block] Next, let's increment your newly-created counter. Just click the **plus button** (+) to the right of any counter, and voila! You've incremented your first counter. [block:image] { "images": [ { "image": [ "https://files.readme.io/7Y5UKR7R8aEis2rb5wIQ_two_counters_with_count.png", "two_counters_with_count.png", "2842", "1210", "#5bb672", "" ] } ] } [/block] [block:callout] { "type": "warning", "body": "Increment/Decrement requests are applied across various counter <a href=\"https://en.wikipedia.org/wiki/Shard_(database_architecture)\" target=\"_blank\">shards</a>, so it's not practical to return the current count of a counter after these types of operations. Instead, to get the real, current count, simply perform an HTTP GET to a counter resource.", "title": "Determining the True Count of a Counter" } [/block] [block:api-header] { "type": "basic", "title": "Appendix: cURL Equivalents" } [/block] You can always use the Dashboard to make calls to Instacount. However, sometimes it's easier to test things out on the command line. The following examples show what you did above, but using cURL. [block:code] { "codes": [ { "code": "curl -X POST --include 'https://api.instacount.io/sharded_counters' \\\n -H 'Accept: application/vnd.instacount.v1+json' \\\n -H 'Content-Type: application/vnd.instacount.v1+json' \\\n -H 'X-Instacount-API-Key: {required, see Instacount Dashboard}' \\\n -H 'X-Instacount-Application-Id: {required, see Instacount Dashboard}'", "language": "curl", "name": "Create a Counter" } ] } [/block] [block:callout] { "type": "success", "title": "New Counter Names", "body": "If you create a counter without specifying a **name** attribute, rely on the **Location** response header to obtain a URL to the newly created counter resource. You can find your new counter's name by performing a GET on this URL and inspecting the **name** attribute in the returned JSON response representation." } [/block] Once you've created a counter, you can access its details via the following call. Be sure to replace the *{counter_name}* value in the request below with the actual name of the counter you created above. [block:code] { "codes": [ { "code": "curl -X GET \\\n-H 'Accept: application/vnd.instacount.v1+json' \\\n-H 'X-Instacount-API-Key: {required, see Instacount Dashboard}' \\\n-H 'X-Instacount-Application-Id: {required, see Instacount Dashboard}' \\\n 'https://api.instacount.io/sharded_counters/{counter_name}' ", "language": "curl", "name": "Get a Counter by Name" } ] } [/block] Finally, here's how to increment your counter: [block:code] { "codes": [ { "code": "curl -X POST \\\n -H \"Accept: application/vnd.instacount.v1+json\" \\\n -H \"Content-Type: application/vnd.instacount.v1+json\" \\\n -H \"X-Instacount-API-Key: {required, see Instacount Dashboard}\" \\\n -H \"X-Instacount-Application-Id: {required, see Instacount Dashboard}\" \\\n -d '{ \"amount\": 1, \"async\": false }'\\\n 'http://localhost:8081/sharded_counters/{counter_name}/increments'", "language": "curl", "name": "Increment a Counter" } ] } [/block] And, here's how to decrement your counter: [block:code] { "codes": [ { "code": "curl -X POST \\\n -H \"Accept: application/vnd.instacount.v1+json\" \\\n -H \"Content-Type: application/vnd.instacount.v1+json\" \\\n -H \"X-Instacount-API-Key: <required, see Instacount Dashboard>\" \\\n -H \"X-Instacount-Application-Id: <required, see Instacount Dashboard>\" \\\n -d '{ \"amount\": 1, \"async\": false }'\\\n 'http://localhost:8081/sharded_counters/{counter_name}/decrements'", "language": "curl", "name": "Decrement a Counter" } ] } [/block]