{"_id":"5652d742a3de712b00d176de","category":"5652d741a3de712b00d176dc","link_external":false,"order":0,"parentDoc":null,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Requirements\"\n}\n[/block]\n- node.js & npm\n- java8\n- elasticsearch\n- redis (optional)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Manual installation\"\n}\n[/block]\nThere are two ways of installation:\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The first way is more standalone and better for non node.js developer\"\n}\n[/block]\n\nClone ItemAPI repository from github:\n```\n$ git clone git@github.com:itemsapi/itemsapi.git\n```\n\nInstall all node.js packages\n```\n$ npm install\n```\n\nStarting app\n```\n$ node app.js\n```\n\nOr even better use process manager `pm2`. App will work in background\n```\n$ pm2 start app.js\n```\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The second way is more flexible and powerful. It is the extension of express \\\"Route\\\" and allows you to provide only API for mobile or web app but also make great node.js applications too\"\n}\n[/block]\nInit project:\n```\n$ npm init\n```\n\nInstall itemsapi:\n```\n$ npm install itemsapi --save\n```\n\nYou can use itemsapi in your node.js app or just start a server in one file\n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var itemsapi = require('itemsapi');\\n\\nitemsapi.init({\\n  server: {\\n    port: 5000\\n  },\\n  collections: {\\n    db: 'json',\\n    filename:  './collections.json'\\n  },\\n  elasticsearch: {\\n    host: 'localhost:9200'\\n  }\\n})\\n\\nitemsapi.start(function serverStart(serverInstance) {\\n  var host = serverInstance.address().address;\\n  var port = serverInstance.address().port;\\n  itemsapi.get('logger').info('ItemsAPI backend started on http://%s:%s', host, port)\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"ItemsAPI server\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Automated installation\"\n}\n[/block]\nWe have plan to make automated installation with ansible, vagrant and separate with docker.\nCurrently it is in built.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"ItemsAPI alpha version\",\n  \"body\": \"ItemsAPI is still in early alpha release. \\nWe work on: \\n- making JSON response format more stable and flexible to many projects.\\n- making configuration layer more flexible too\\n- adding more tests\"\n}\n[/block]","createdAt":"2015-11-23T09:07:14.248Z","excerpt":"This page will help you get started with Itemsapi. You'll be up and running in a jiffy!","githubsync":"","hidden":false,"isReference":false,"project":"5652d740a3de712b00d176d8","__v":27,"title":"Installing ItemsAPI","link_url":"","version":"5652d740a3de712b00d176db","api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"sync_unique":"","type":"basic","updates":["572cd9f441ad002d00ddc712"],"user":"5652d72cfab156210023d20a","slug":"getting-started","childrenPages":[]}

Installing ItemsAPI

This page will help you get started with Itemsapi. You'll be up and running in a jiffy!
[block:api-header] { "type": "basic", "title": "Requirements" } [/block] - node.js & npm - java8 - elasticsearch - redis (optional) [block:api-header] { "type": "basic", "title": "Manual installation" } [/block] There are two ways of installation: [block:callout] { "type": "info", "body": "The first way is more standalone and better for non node.js developer" } [/block] Clone ItemAPI repository from github: ``` $ git clone git@github.com:itemsapi/itemsapi.git ``` Install all node.js packages ``` $ npm install ``` Starting app ``` $ node app.js ``` Or even better use process manager `pm2`. App will work in background ``` $ pm2 start app.js ``` [block:callout] { "type": "info", "body": "The second way is more flexible and powerful. It is the extension of express \"Route\" and allows you to provide only API for mobile or web app but also make great node.js applications too" } [/block] Init project: ``` $ npm init ``` Install itemsapi: ``` $ npm install itemsapi --save ``` You can use itemsapi in your node.js app or just start a server in one file [block:code] { "codes": [ { "code": "var itemsapi = require('itemsapi');\n\nitemsapi.init({\n server: {\n port: 5000\n },\n collections: {\n db: 'json',\n filename: './collections.json'\n },\n elasticsearch: {\n host: 'localhost:9200'\n }\n})\n\nitemsapi.start(function serverStart(serverInstance) {\n var host = serverInstance.address().address;\n var port = serverInstance.address().port;\n itemsapi.get('logger').info('ItemsAPI backend started on http://%s:%s', host, port)\n});", "language": "javascript", "name": "ItemsAPI server" } ] } [/block] [block:api-header] { "type": "basic", "title": "Automated installation" } [/block] We have plan to make automated installation with ansible, vagrant and separate with docker. Currently it is in built. [block:callout] { "type": "warning", "title": "ItemsAPI alpha version", "body": "ItemsAPI is still in early alpha release. \nWe work on: \n- making JSON response format more stable and flexible to many projects.\n- making configuration layer more flexible too\n- adding more tests" } [/block]
[block:api-header] { "type": "basic", "title": "Requirements" } [/block] - node.js & npm - java8 - elasticsearch - redis (optional) [block:api-header] { "type": "basic", "title": "Manual installation" } [/block] There are two ways of installation: [block:callout] { "type": "info", "body": "The first way is more standalone and better for non node.js developer" } [/block] Clone ItemAPI repository from github: ``` $ git clone git@github.com:itemsapi/itemsapi.git ``` Install all node.js packages ``` $ npm install ``` Starting app ``` $ node app.js ``` Or even better use process manager `pm2`. App will work in background ``` $ pm2 start app.js ``` [block:callout] { "type": "info", "body": "The second way is more flexible and powerful. It is the extension of express \"Route\" and allows you to provide only API for mobile or web app but also make great node.js applications too" } [/block] Init project: ``` $ npm init ``` Install itemsapi: ``` $ npm install itemsapi --save ``` You can use itemsapi in your node.js app or just start a server in one file [block:code] { "codes": [ { "code": "var itemsapi = require('itemsapi');\n\nitemsapi.init({\n server: {\n port: 5000\n },\n collections: {\n db: 'json',\n filename: './collections.json'\n },\n elasticsearch: {\n host: 'localhost:9200'\n }\n})\n\nitemsapi.start(function serverStart(serverInstance) {\n var host = serverInstance.address().address;\n var port = serverInstance.address().port;\n itemsapi.get('logger').info('ItemsAPI backend started on http://%s:%s', host, port)\n});", "language": "javascript", "name": "ItemsAPI server" } ] } [/block] [block:api-header] { "type": "basic", "title": "Automated installation" } [/block] We have plan to make automated installation with ansible, vagrant and separate with docker. Currently it is in built. [block:callout] { "type": "warning", "title": "ItemsAPI alpha version", "body": "ItemsAPI is still in early alpha release. \nWe work on: \n- making JSON response format more stable and flexible to many projects.\n- making configuration layer more flexible too\n- adding more tests" } [/block]
{"_id":"5652e379bbe7110d00dba74f","body":"We want to make deployment as simple as possible to the cloud servers.\nIt will give possibility for better scalability when necessary \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Option 1: Heroku\"\n}\n[/block]\nDeploying to heroku is extremely easy. You can install in one click and create backend with creator in few minutes.\n<a target=\"_blank\" href=\"https://heroku.com/deploy?template=https://github.com/itemsapi/itemsapi-starter\"><img src=\"https://camo.githubusercontent.com/c0824806f5221ebb7d25e559568582dd39dd1170/68747470733a2f2f7777772e6865726f6b7563646e2e636f6d2f6465706c6f792f627574746f6e2e706e67\" alt=\"Deploy\" data-canonical-src=\"https://www.herokucdn.com/deploy/button.png\"></a>\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/zugKj5NZRk6W703S0lW3_Selection_258.jpg\",\n        \"Selection_258.jpg\",\n        \"759\",\n        \"953\",\n        \"#5283a2\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Option 2: DigitalOcean\"\n}\n[/block]\nIn progress..","hidden":false,"title":"Deploying (heroku)","user":"5652d72cfab156210023d20a","version":"5652d740a3de712b00d176db","__v":7,"createdAt":"2015-11-23T09:59:21.617Z","excerpt":"Deploy your app fast to cloud servers","order":1,"project":"5652d740a3de712b00d176d8","slug":"deploying","category":"5652d741a3de712b00d176dc","link_external":false,"updates":[],"api":{"url":"","auth":"required","params":[],"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"settings":""},"githubsync":"","isReference":false,"link_url":"","parentDoc":null,"sync_unique":"","type":"basic","childrenPages":[]}

Deploying (heroku)

Deploy your app fast to cloud servers
We want to make deployment as simple as possible to the cloud servers. It will give possibility for better scalability when necessary [block:api-header] { "type": "basic", "title": "Option 1: Heroku" } [/block] Deploying to heroku is extremely easy. You can install in one click and create backend with creator in few minutes. <a target="_blank" href="https://heroku.com/deploy?template=https://github.com/itemsapi/itemsapi-starter"><img src="https://camo.githubusercontent.com/c0824806f5221ebb7d25e559568582dd39dd1170/68747470733a2f2f7777772e6865726f6b7563646e2e636f6d2f6465706c6f792f627574746f6e2e706e67" alt="Deploy" data-canonical-src="https://www.herokucdn.com/deploy/button.png"></a> [block:image] { "images": [ { "image": [ "https://files.readme.io/zugKj5NZRk6W703S0lW3_Selection_258.jpg", "Selection_258.jpg", "759", "953", "#5283a2", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Option 2: DigitalOcean" } [/block] In progress..
We want to make deployment as simple as possible to the cloud servers. It will give possibility for better scalability when necessary [block:api-header] { "type": "basic", "title": "Option 1: Heroku" } [/block] Deploying to heroku is extremely easy. You can install in one click and create backend with creator in few minutes. <a target="_blank" href="https://heroku.com/deploy?template=https://github.com/itemsapi/itemsapi-starter"><img src="https://camo.githubusercontent.com/c0824806f5221ebb7d25e559568582dd39dd1170/68747470733a2f2f7777772e6865726f6b7563646e2e636f6d2f6465706c6f792f627574746f6e2e706e67" alt="Deploy" data-canonical-src="https://www.herokucdn.com/deploy/button.png"></a> [block:image] { "images": [ { "image": [ "https://files.readme.io/zugKj5NZRk6W703S0lW3_Selection_258.jpg", "Selection_258.jpg", "759", "953", "#5283a2", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Option 2: DigitalOcean" } [/block] In progress..
{"_id":"5652e82fbbe7110d00dba754","isReference":false,"slug":"configuration","type":"basic","updates":["565e34298f048c2100442a40"],"createdAt":"2015-11-23T10:19:27.232Z","excerpt":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"5652d740a3de712b00d176d8","__v":26,"githubsync":"","body":"Configuration files are based in `./config/` directory. The main configuration file is `root.json`. \n\nBelow is example of configuration:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"elasticsearch\\\": {\\n    \\\"host\\\": \\\"localhost:9200\\\",\\n    \\\"log\\\": \\\"error\\\"\\n  },\\n  \\\"redis\\\": {\\n    \\\"host\\\": \\\"127.0.0.1\\\",\\n    \\\"port\\\": 6379,\\n    \\\"auth_pass\\\": null\\n  },\\n  \\\"server\\\": {\\n    \\\"host\\\": \\\"http://127.0.0.1\\\",\\n    \\\"port\\\": 3000\\n  },\\n  \\\"collections\\\": {\\n    \\\"db\\\": \\\"json\\\",\\n    \\\"filename\\\":  \\\"./config/collections.json\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"root.json\"\n    }\n  ]\n}\n[/block]\nYou can override it with `./config/local.json`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"collections\\\": {\\n    \\\"db\\\": \\\"json\\\",\\n    \\\"filename\\\":  \\\"./config/local/my-local-collections.json\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"local.json\"\n    }\n  ]\n}\n[/block]\nAs you see it is quite flexible.\n\nYou can override configurations programmatically if you use itemsapi in node.js script:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var itemsapi = require('itemsapi');\\n\\nitemsapi.init({\\n  server: {\\n    port: 5000\\n  },\\n  collections: {\\n    db: 'json',\\n    filename:  './collections.json'\\n  },\\n  elasticsearch: {\\n    host: 'localhost:9200'\\n  }\\n}) \",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nYou can even extend express.js to make additionals endpoints i.e. yourdomain.com/about-us:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var itemsapi = require('./server');\\nitemsapi.init({})\\n\\n// standard express syntax\\nvar express = itemsapi.get('express');\\nexpress.get('/about-us', function(req, res) {\\n  res.json({\\n    name: 'itemsapi',\\n    license: 'MIT'\\n  });\\n});\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Collections configuration\"\n}\n[/block]\nIn config file we include `collections` configuration which currently is stored in JSON file.\nThe simple example of `collections` is:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"name\\\": \\\"movie\\\",\\n    \\\"project\\\": \\\"itemsapi\\\",\\n    \\\"schema\\\": {\\n      \\\"name\\\": {\\\"type\\\": \\\"string\\\", \\\"store\\\": true },\\n      \\\"image\\\": {\\\"type\\\": \\\"string\\\", \\\"display\\\": \\\"image\\\" },\\n      \\\"year\\\": {\\\"type\\\": \\\"integer\\\", \\\"store\\\": true },\\n      \\\"votes\\\": {\\\"type\\\": \\\"integer\\\", \\\"store\\\": true },\\n      \\\"director\\\": {\\\"type\\\": \\\"string\\\", \\\"index\\\": \\\"not_analyzed\\\", \\\"store\\\": true },\\n      \\\"actors\\\": {\\\"type\\\": \\\"string\\\", \\\"index\\\": \\\"not_analyzed\\\", \\\"display\\\": \\\"array\\\", \\\"store\\\": true },\\n      \\\"tags\\\": {\\\"type\\\": \\\"string\\\", \\\"display\\\": \\\"array\\\", \\\"store\\\": true },\\n      \\\"rating\\\": {\\\"type\\\": \\\"float\\\", \\\"store\\\": true }\\n    },\\n    \\\"table\\\": {\\n      \\\"fields\\\": [\\\"image\\\", \\\"name\\\", \\\"director\\\", \\\"rating\\\", \\\"year\\\", \\\"votes\\\", \\\"tags\\\", \\\"actors\\\"]\\n    }\\n  }\\n]\",\n      \"language\": \"json\",\n      \"name\": \"collections.json\"\n    }\n  ]\n}\n[/block]\nBelow is version with `aggregations` and `sortings`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"name\\\": \\\"movie\\\",\\n    \\\"project\\\": \\\"itemsapi\\\",\\n    \\\"meta\\\": {\\n      \\\"title\\\": \\\"Movies\\\",\\n      \\\"created\\\": \\\"spring 2015\\\"\\n    },\\n    \\\"schema\\\": {\\n      \\\"name\\\": {\\\"type\\\": \\\"string\\\", \\\"store\\\": true },\\n      \\\"image\\\": {\\\"type\\\": \\\"string\\\", \\\"display\\\": \\\"image\\\" },\\n      \\\"year\\\": {\\\"type\\\": \\\"integer\\\", \\\"store\\\": true },\\n      \\\"votes\\\": {\\\"type\\\": \\\"integer\\\", \\\"store\\\": true },\\n      \\\"director\\\": {\\\"type\\\": \\\"string\\\", \\\"index\\\": \\\"not_analyzed\\\", \\\"store\\\": true },\\n      \\\"actors\\\": {\\\"type\\\": \\\"string\\\", \\\"index\\\": \\\"not_analyzed\\\", \\\"display\\\": \\\"array\\\", \\\"store\\\": true },\\n      \\\"tags\\\": {\\\"type\\\": \\\"string\\\", \\\"display\\\": \\\"array\\\", \\\"store\\\": true },\\n      \\\"rating\\\": {\\\"type\\\": \\\"float\\\", \\\"store\\\": true }\\n    },\\n    \\\"sortings\\\": {\\n      \\\"rating\\\": {\\n        \\\"title\\\": \\\"Best rating\\\",\\n        \\\"type\\\": \\\"normal\\\",\\n        \\\"order\\\": \\\"desc\\\",\\n        \\\"field\\\": \\\"rating\\\"\\n      },\\n      \\\"most_votes\\\": {\\n        \\\"title\\\": \\\"Most votes\\\",\\n        \\\"type\\\": \\\"normal\\\",\\n        \\\"order\\\": \\\"desc\\\",\\n        \\\"field\\\": \\\"votes\\\"\\n      },\\n      \\\"year_newest\\\": {\\n        \\\"title\\\": \\\"Newest movies\\\",\\n        \\\"type\\\": \\\"normal\\\",\\n        \\\"order\\\": \\\"desc\\\",\\n        \\\"field\\\": \\\"year\\\"\\n      },\\n      \\\"year_oldest\\\": {\\n        \\\"title\\\": \\\"Oldest movies\\\",\\n        \\\"type\\\": \\\"normal\\\",\\n        \\\"order\\\": \\\"asc\\\",\\n        \\\"field\\\": \\\"year\\\"\\n      }\\n    },\\n    \\\"slugs\\\": [\\\"actors\\\"],\\n    \\\"aggregations\\\": {\\n      \\\"actors_terms\\\": {\\\"type\\\": \\\"terms\\\", \\\"field\\\": \\\"actors\\\", \\\"size\\\": 10, \\\"title\\\": \\\"Actors\\\"},\\n      \\\"director_terms\\\": {\\\"type\\\": \\\"terms\\\", \\\"field\\\": \\\"director\\\", \\\"size\\\": 5, \\\"title\\\": \\\"Directors\\\"},\\n      \\\"tags_terms\\\": {\\\"type\\\": \\\"terms\\\", \\\"field\\\": \\\"tags\\\", \\\"size\\\": 10, \\\"title\\\": \\\"Tags\\\"},\\n\\n      \\\"votes_range\\\": {\\n        \\\"type\\\": \\\"range\\\",\\n        \\\"field\\\": \\\"votes\\\",\\n        \\\"title\\\": \\\"Votes range\\\",\\n        \\\"ranges\\\": [\\n          {\\\"lte\\\": 300, \\\"name\\\": \\\"< 300\\\"},\\n          {\\\"gte\\\": 300, \\\"lte\\\": 1000, \\\"name\\\": \\\"300 - 1000\\\"},\\n          {\\\"gte\\\": 1000, \\\"lte\\\": 3000, \\\"name\\\": \\\"1000 - 3000\\\"},\\n          {\\\"gte\\\": 3000, \\\"name\\\": \\\"> 3000\\\"}\\n        ]\\n      },\\n      \\\"years_range\\\": {\\n        \\\"type\\\": \\\"range\\\",\\n        \\\"field\\\": \\\"year\\\",\\n        \\\"title\\\": \\\"Years range\\\",\\n        \\\"ranges\\\": [\\n          {\\\"lte\\\": 1950, \\\"name\\\": \\\"1950 - 1960\\\"},\\n          {\\\"gte\\\": 1950, \\\"lte\\\": 1960, \\\"name\\\": \\\"1950 - 1960\\\"},\\n          {\\\"gte\\\": 1960, \\\"lte\\\": 1970, \\\"name\\\": \\\"1960 - 1970\\\"},\\n          {\\\"gte\\\": 1970, \\\"lte\\\": 1980, \\\"name\\\": \\\"1970 - 1980\\\"},\\n          {\\\"gte\\\": 1980, \\\"lte\\\": 1990, \\\"name\\\": \\\"1980 - 1990\\\"},\\n          {\\\"gte\\\": 1990, \\\"lte\\\": 2000, \\\"name\\\": \\\"1990 - 2000\\\"},\\n          {\\\"gte\\\": 2000, \\\"lte\\\": 2010, \\\"name\\\": \\\"2000 - 2010\\\"},\\n          {\\\"gte\\\": 2010, \\\"name\\\": \\\"> 2010\\\"}\\n        ]\\n      },\\n      \\\"rating_range\\\": {\\n        \\\"type\\\": \\\"range\\\",\\n        \\\"field\\\": \\\"rating\\\",\\n        \\\"title\\\": \\\"Rating range\\\",\\n        \\\"ranges\\\": [\\n          {\\\"lte\\\": 1, \\\"name\\\": \\\"0 - 1\\\"},\\n          {\\\"gte\\\": 1, \\\"lte\\\": 2, \\\"name\\\": \\\"1 - 2\\\"},\\n          {\\\"gte\\\": 2, \\\"lte\\\": 3, \\\"name\\\": \\\"2 - 3\\\"},\\n          {\\\"gte\\\": 3, \\\"lte\\\": 4, \\\"name\\\": \\\"3 - 4\\\"},\\n          {\\\"gte\\\": 4, \\\"lte\\\": 5, \\\"name\\\": \\\"4 - 5\\\"},\\n          {\\\"gte\\\": 5, \\\"lte\\\": 6, \\\"name\\\": \\\"5 - 6\\\"},\\n          {\\\"gte\\\": 6, \\\"lte\\\": 7, \\\"name\\\": \\\"6 - 7\\\"},\\n          {\\\"gte\\\": 7, \\\"lte\\\": 8, \\\"name\\\": \\\"7 - 8\\\"},\\n          {\\\"gte\\\": 8, \\\"lte\\\": 9, \\\"name\\\": \\\"8 - 9\\\"},\\n          {\\\"gte\\\": 9, \\\"name\\\": \\\"9 - 10\\\"}\\n        ]\\n      }\\n    },\\n    \\\"table\\\": {\\n      \\\"fields\\\": [\\\"image\\\", \\\"name\\\", \\\"director\\\", \\\"rating\\\", \\\"year\\\", \\\"votes\\\", \\\"tags\\\", \\\"actors\\\"]\\n    }\\n  }\\n]\",\n      \"language\": \"json\",\n      \"name\": \"collections.json\"\n    }\n  ]\n}\n[/block]\nIt is quite long but very powerful and it is responsible for the API generation and whole logic.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"schema\",\n  \"body\": \"`schema` is responsible for storing fields as `integer`, `string`, `float`, etc and which fields should be searchable\\n\\nMore details are in elasticsearch docs https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"aggregations\",\n  \"body\": \"`aggregations` generate automatically powerful filters. You don't need anymore over complicated and slow `mysql` queries to do that. Here it works out of the box.\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/eExNiMRLuVFH7UcL7KJw_Selection_344.png\",\n        \"Selection_344.png\",\n        \"379\",\n        \"603\",\n        \"#935642\",\n        \"\"\n      ],\n      \"caption\": \"aggregations options\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"sortings\",\n  \"body\": \"`sortings` is small specification on which and how to sort items - i.e. `/api/v1/movie/?sort=year_oldest`\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"slugs\",\n  \"body\": \"Slugs options allows you to define which fields should be slugified (for pretty url) out of the box.\\n\\nWhen you set slugs as [\\\"actors\\\"] then you could search items by such a urls \\\"filter/actors/tom-hanks\\\" instead of \\\"filter/actors/Tom%20Hanks\\\" which is much better for SEO\\n(this feature require redis enabled)\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/u9gXmBbnSdCxvTg878Cj_Selection_251.jpg\",\n        \"Selection_251.jpg\",\n        \"262\",\n        \"36\",\n        \"#f1f1f1\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]","category":"5652d741a3de712b00d176dc","parentDoc":null,"sync_unique":"","api":{"params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"","auth":"required"},"version":"5652d740a3de712b00d176db","title":"Configuration","user":"5652d72cfab156210023d20a","childrenPages":[]}

Configuration

Configuration files are based in `./config/` directory. The main configuration file is `root.json`. Below is example of configuration: [block:code] { "codes": [ { "code": "{\n \"elasticsearch\": {\n \"host\": \"localhost:9200\",\n \"log\": \"error\"\n },\n \"redis\": {\n \"host\": \"127.0.0.1\",\n \"port\": 6379,\n \"auth_pass\": null\n },\n \"server\": {\n \"host\": \"http://127.0.0.1\",\n \"port\": 3000\n },\n \"collections\": {\n \"db\": \"json\",\n \"filename\": \"./config/collections.json\"\n }\n}", "language": "json", "name": "root.json" } ] } [/block] You can override it with `./config/local.json` [block:code] { "codes": [ { "code": "{\n \"collections\": {\n \"db\": \"json\",\n \"filename\": \"./config/local/my-local-collections.json\"\n }\n}", "language": "json", "name": "local.json" } ] } [/block] As you see it is quite flexible. You can override configurations programmatically if you use itemsapi in node.js script: [block:code] { "codes": [ { "code": "var itemsapi = require('itemsapi');\n\nitemsapi.init({\n server: {\n port: 5000\n },\n collections: {\n db: 'json',\n filename: './collections.json'\n },\n elasticsearch: {\n host: 'localhost:9200'\n }\n}) ", "language": "javascript" } ] } [/block] You can even extend express.js to make additionals endpoints i.e. yourdomain.com/about-us: [block:code] { "codes": [ { "code": "var itemsapi = require('./server');\nitemsapi.init({})\n\n// standard express syntax\nvar express = itemsapi.get('express');\nexpress.get('/about-us', function(req, res) {\n res.json({\n name: 'itemsapi',\n license: 'MIT'\n });\n});\n", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Collections configuration" } [/block] In config file we include `collections` configuration which currently is stored in JSON file. The simple example of `collections` is: [block:code] { "codes": [ { "code": "[\n {\n \"name\": \"movie\",\n \"project\": \"itemsapi\",\n \"schema\": {\n \"name\": {\"type\": \"string\", \"store\": true },\n \"image\": {\"type\": \"string\", \"display\": \"image\" },\n \"year\": {\"type\": \"integer\", \"store\": true },\n \"votes\": {\"type\": \"integer\", \"store\": true },\n \"director\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"store\": true },\n \"actors\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"display\": \"array\", \"store\": true },\n \"tags\": {\"type\": \"string\", \"display\": \"array\", \"store\": true },\n \"rating\": {\"type\": \"float\", \"store\": true }\n },\n \"table\": {\n \"fields\": [\"image\", \"name\", \"director\", \"rating\", \"year\", \"votes\", \"tags\", \"actors\"]\n }\n }\n]", "language": "json", "name": "collections.json" } ] } [/block] Below is version with `aggregations` and `sortings`: [block:code] { "codes": [ { "code": "[\n {\n \"name\": \"movie\",\n \"project\": \"itemsapi\",\n \"meta\": {\n \"title\": \"Movies\",\n \"created\": \"spring 2015\"\n },\n \"schema\": {\n \"name\": {\"type\": \"string\", \"store\": true },\n \"image\": {\"type\": \"string\", \"display\": \"image\" },\n \"year\": {\"type\": \"integer\", \"store\": true },\n \"votes\": {\"type\": \"integer\", \"store\": true },\n \"director\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"store\": true },\n \"actors\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"display\": \"array\", \"store\": true },\n \"tags\": {\"type\": \"string\", \"display\": \"array\", \"store\": true },\n \"rating\": {\"type\": \"float\", \"store\": true }\n },\n \"sortings\": {\n \"rating\": {\n \"title\": \"Best rating\",\n \"type\": \"normal\",\n \"order\": \"desc\",\n \"field\": \"rating\"\n },\n \"most_votes\": {\n \"title\": \"Most votes\",\n \"type\": \"normal\",\n \"order\": \"desc\",\n \"field\": \"votes\"\n },\n \"year_newest\": {\n \"title\": \"Newest movies\",\n \"type\": \"normal\",\n \"order\": \"desc\",\n \"field\": \"year\"\n },\n \"year_oldest\": {\n \"title\": \"Oldest movies\",\n \"type\": \"normal\",\n \"order\": \"asc\",\n \"field\": \"year\"\n }\n },\n \"slugs\": [\"actors\"],\n \"aggregations\": {\n \"actors_terms\": {\"type\": \"terms\", \"field\": \"actors\", \"size\": 10, \"title\": \"Actors\"},\n \"director_terms\": {\"type\": \"terms\", \"field\": \"director\", \"size\": 5, \"title\": \"Directors\"},\n \"tags_terms\": {\"type\": \"terms\", \"field\": \"tags\", \"size\": 10, \"title\": \"Tags\"},\n\n \"votes_range\": {\n \"type\": \"range\",\n \"field\": \"votes\",\n \"title\": \"Votes range\",\n \"ranges\": [\n {\"lte\": 300, \"name\": \"< 300\"},\n {\"gte\": 300, \"lte\": 1000, \"name\": \"300 - 1000\"},\n {\"gte\": 1000, \"lte\": 3000, \"name\": \"1000 - 3000\"},\n {\"gte\": 3000, \"name\": \"> 3000\"}\n ]\n },\n \"years_range\": {\n \"type\": \"range\",\n \"field\": \"year\",\n \"title\": \"Years range\",\n \"ranges\": [\n {\"lte\": 1950, \"name\": \"1950 - 1960\"},\n {\"gte\": 1950, \"lte\": 1960, \"name\": \"1950 - 1960\"},\n {\"gte\": 1960, \"lte\": 1970, \"name\": \"1960 - 1970\"},\n {\"gte\": 1970, \"lte\": 1980, \"name\": \"1970 - 1980\"},\n {\"gte\": 1980, \"lte\": 1990, \"name\": \"1980 - 1990\"},\n {\"gte\": 1990, \"lte\": 2000, \"name\": \"1990 - 2000\"},\n {\"gte\": 2000, \"lte\": 2010, \"name\": \"2000 - 2010\"},\n {\"gte\": 2010, \"name\": \"> 2010\"}\n ]\n },\n \"rating_range\": {\n \"type\": \"range\",\n \"field\": \"rating\",\n \"title\": \"Rating range\",\n \"ranges\": [\n {\"lte\": 1, \"name\": \"0 - 1\"},\n {\"gte\": 1, \"lte\": 2, \"name\": \"1 - 2\"},\n {\"gte\": 2, \"lte\": 3, \"name\": \"2 - 3\"},\n {\"gte\": 3, \"lte\": 4, \"name\": \"3 - 4\"},\n {\"gte\": 4, \"lte\": 5, \"name\": \"4 - 5\"},\n {\"gte\": 5, \"lte\": 6, \"name\": \"5 - 6\"},\n {\"gte\": 6, \"lte\": 7, \"name\": \"6 - 7\"},\n {\"gte\": 7, \"lte\": 8, \"name\": \"7 - 8\"},\n {\"gte\": 8, \"lte\": 9, \"name\": \"8 - 9\"},\n {\"gte\": 9, \"name\": \"9 - 10\"}\n ]\n }\n },\n \"table\": {\n \"fields\": [\"image\", \"name\", \"director\", \"rating\", \"year\", \"votes\", \"tags\", \"actors\"]\n }\n }\n]", "language": "json", "name": "collections.json" } ] } [/block] It is quite long but very powerful and it is responsible for the API generation and whole logic. [block:callout] { "type": "info", "title": "schema", "body": "`schema` is responsible for storing fields as `integer`, `string`, `float`, etc and which fields should be searchable\n\nMore details are in elasticsearch docs https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html" } [/block] [block:callout] { "type": "info", "title": "aggregations", "body": "`aggregations` generate automatically powerful filters. You don't need anymore over complicated and slow `mysql` queries to do that. Here it works out of the box." } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/eExNiMRLuVFH7UcL7KJw_Selection_344.png", "Selection_344.png", "379", "603", "#935642", "" ], "caption": "aggregations options" } ] } [/block] [block:callout] { "type": "info", "title": "sortings", "body": "`sortings` is small specification on which and how to sort items - i.e. `/api/v1/movie/?sort=year_oldest`" } [/block] [block:callout] { "type": "info", "title": "slugs", "body": "Slugs options allows you to define which fields should be slugified (for pretty url) out of the box.\n\nWhen you set slugs as [\"actors\"] then you could search items by such a urls \"filter/actors/tom-hanks\" instead of \"filter/actors/Tom%20Hanks\" which is much better for SEO\n(this feature require redis enabled)" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/u9gXmBbnSdCxvTg878Cj_Selection_251.jpg", "Selection_251.jpg", "262", "36", "#f1f1f1", "" ] } ] } [/block]
Configuration files are based in `./config/` directory. The main configuration file is `root.json`. Below is example of configuration: [block:code] { "codes": [ { "code": "{\n \"elasticsearch\": {\n \"host\": \"localhost:9200\",\n \"log\": \"error\"\n },\n \"redis\": {\n \"host\": \"127.0.0.1\",\n \"port\": 6379,\n \"auth_pass\": null\n },\n \"server\": {\n \"host\": \"http://127.0.0.1\",\n \"port\": 3000\n },\n \"collections\": {\n \"db\": \"json\",\n \"filename\": \"./config/collections.json\"\n }\n}", "language": "json", "name": "root.json" } ] } [/block] You can override it with `./config/local.json` [block:code] { "codes": [ { "code": "{\n \"collections\": {\n \"db\": \"json\",\n \"filename\": \"./config/local/my-local-collections.json\"\n }\n}", "language": "json", "name": "local.json" } ] } [/block] As you see it is quite flexible. You can override configurations programmatically if you use itemsapi in node.js script: [block:code] { "codes": [ { "code": "var itemsapi = require('itemsapi');\n\nitemsapi.init({\n server: {\n port: 5000\n },\n collections: {\n db: 'json',\n filename: './collections.json'\n },\n elasticsearch: {\n host: 'localhost:9200'\n }\n}) ", "language": "javascript" } ] } [/block] You can even extend express.js to make additionals endpoints i.e. yourdomain.com/about-us: [block:code] { "codes": [ { "code": "var itemsapi = require('./server');\nitemsapi.init({})\n\n// standard express syntax\nvar express = itemsapi.get('express');\nexpress.get('/about-us', function(req, res) {\n res.json({\n name: 'itemsapi',\n license: 'MIT'\n });\n});\n", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Collections configuration" } [/block] In config file we include `collections` configuration which currently is stored in JSON file. The simple example of `collections` is: [block:code] { "codes": [ { "code": "[\n {\n \"name\": \"movie\",\n \"project\": \"itemsapi\",\n \"schema\": {\n \"name\": {\"type\": \"string\", \"store\": true },\n \"image\": {\"type\": \"string\", \"display\": \"image\" },\n \"year\": {\"type\": \"integer\", \"store\": true },\n \"votes\": {\"type\": \"integer\", \"store\": true },\n \"director\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"store\": true },\n \"actors\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"display\": \"array\", \"store\": true },\n \"tags\": {\"type\": \"string\", \"display\": \"array\", \"store\": true },\n \"rating\": {\"type\": \"float\", \"store\": true }\n },\n \"table\": {\n \"fields\": [\"image\", \"name\", \"director\", \"rating\", \"year\", \"votes\", \"tags\", \"actors\"]\n }\n }\n]", "language": "json", "name": "collections.json" } ] } [/block] Below is version with `aggregations` and `sortings`: [block:code] { "codes": [ { "code": "[\n {\n \"name\": \"movie\",\n \"project\": \"itemsapi\",\n \"meta\": {\n \"title\": \"Movies\",\n \"created\": \"spring 2015\"\n },\n \"schema\": {\n \"name\": {\"type\": \"string\", \"store\": true },\n \"image\": {\"type\": \"string\", \"display\": \"image\" },\n \"year\": {\"type\": \"integer\", \"store\": true },\n \"votes\": {\"type\": \"integer\", \"store\": true },\n \"director\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"store\": true },\n \"actors\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"display\": \"array\", \"store\": true },\n \"tags\": {\"type\": \"string\", \"display\": \"array\", \"store\": true },\n \"rating\": {\"type\": \"float\", \"store\": true }\n },\n \"sortings\": {\n \"rating\": {\n \"title\": \"Best rating\",\n \"type\": \"normal\",\n \"order\": \"desc\",\n \"field\": \"rating\"\n },\n \"most_votes\": {\n \"title\": \"Most votes\",\n \"type\": \"normal\",\n \"order\": \"desc\",\n \"field\": \"votes\"\n },\n \"year_newest\": {\n \"title\": \"Newest movies\",\n \"type\": \"normal\",\n \"order\": \"desc\",\n \"field\": \"year\"\n },\n \"year_oldest\": {\n \"title\": \"Oldest movies\",\n \"type\": \"normal\",\n \"order\": \"asc\",\n \"field\": \"year\"\n }\n },\n \"slugs\": [\"actors\"],\n \"aggregations\": {\n \"actors_terms\": {\"type\": \"terms\", \"field\": \"actors\", \"size\": 10, \"title\": \"Actors\"},\n \"director_terms\": {\"type\": \"terms\", \"field\": \"director\", \"size\": 5, \"title\": \"Directors\"},\n \"tags_terms\": {\"type\": \"terms\", \"field\": \"tags\", \"size\": 10, \"title\": \"Tags\"},\n\n \"votes_range\": {\n \"type\": \"range\",\n \"field\": \"votes\",\n \"title\": \"Votes range\",\n \"ranges\": [\n {\"lte\": 300, \"name\": \"< 300\"},\n {\"gte\": 300, \"lte\": 1000, \"name\": \"300 - 1000\"},\n {\"gte\": 1000, \"lte\": 3000, \"name\": \"1000 - 3000\"},\n {\"gte\": 3000, \"name\": \"> 3000\"}\n ]\n },\n \"years_range\": {\n \"type\": \"range\",\n \"field\": \"year\",\n \"title\": \"Years range\",\n \"ranges\": [\n {\"lte\": 1950, \"name\": \"1950 - 1960\"},\n {\"gte\": 1950, \"lte\": 1960, \"name\": \"1950 - 1960\"},\n {\"gte\": 1960, \"lte\": 1970, \"name\": \"1960 - 1970\"},\n {\"gte\": 1970, \"lte\": 1980, \"name\": \"1970 - 1980\"},\n {\"gte\": 1980, \"lte\": 1990, \"name\": \"1980 - 1990\"},\n {\"gte\": 1990, \"lte\": 2000, \"name\": \"1990 - 2000\"},\n {\"gte\": 2000, \"lte\": 2010, \"name\": \"2000 - 2010\"},\n {\"gte\": 2010, \"name\": \"> 2010\"}\n ]\n },\n \"rating_range\": {\n \"type\": \"range\",\n \"field\": \"rating\",\n \"title\": \"Rating range\",\n \"ranges\": [\n {\"lte\": 1, \"name\": \"0 - 1\"},\n {\"gte\": 1, \"lte\": 2, \"name\": \"1 - 2\"},\n {\"gte\": 2, \"lte\": 3, \"name\": \"2 - 3\"},\n {\"gte\": 3, \"lte\": 4, \"name\": \"3 - 4\"},\n {\"gte\": 4, \"lte\": 5, \"name\": \"4 - 5\"},\n {\"gte\": 5, \"lte\": 6, \"name\": \"5 - 6\"},\n {\"gte\": 6, \"lte\": 7, \"name\": \"6 - 7\"},\n {\"gte\": 7, \"lte\": 8, \"name\": \"7 - 8\"},\n {\"gte\": 8, \"lte\": 9, \"name\": \"8 - 9\"},\n {\"gte\": 9, \"name\": \"9 - 10\"}\n ]\n }\n },\n \"table\": {\n \"fields\": [\"image\", \"name\", \"director\", \"rating\", \"year\", \"votes\", \"tags\", \"actors\"]\n }\n }\n]", "language": "json", "name": "collections.json" } ] } [/block] It is quite long but very powerful and it is responsible for the API generation and whole logic. [block:callout] { "type": "info", "title": "schema", "body": "`schema` is responsible for storing fields as `integer`, `string`, `float`, etc and which fields should be searchable\n\nMore details are in elasticsearch docs https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html" } [/block] [block:callout] { "type": "info", "title": "aggregations", "body": "`aggregations` generate automatically powerful filters. You don't need anymore over complicated and slow `mysql` queries to do that. Here it works out of the box." } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/eExNiMRLuVFH7UcL7KJw_Selection_344.png", "Selection_344.png", "379", "603", "#935642", "" ], "caption": "aggregations options" } ] } [/block] [block:callout] { "type": "info", "title": "sortings", "body": "`sortings` is small specification on which and how to sort items - i.e. `/api/v1/movie/?sort=year_oldest`" } [/block] [block:callout] { "type": "info", "title": "slugs", "body": "Slugs options allows you to define which fields should be slugified (for pretty url) out of the box.\n\nWhen you set slugs as [\"actors\"] then you could search items by such a urls \"filter/actors/tom-hanks\" instead of \"filter/actors/Tom%20Hanks\" which is much better for SEO\n(this feature require redis enabled)" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/u9gXmBbnSdCxvTg878Cj_Selection_251.jpg", "Selection_251.jpg", "262", "36", "#f1f1f1", "" ] } ] } [/block]
{"_id":"5735b0d831a73b1700887e6c","slug":"schema","user":"5652d72cfab156210023d20a","__v":1,"link_external":false,"hidden":false,"link_url":"","sync_unique":"","type":"basic","updates":[],"body":"Schema is responsible for fields types and how fields are `stored` and `searched`\nSchema is compatible with elasticsearch schema (https://www.elastic.co/guide/en/elasticsearch/reference/1.7/mapping-core-types.html)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"schema\\\": {\\n    \\\"name\\\": {\\\"type\\\": \\\"string\\\", \\\"store\\\": true },\\n    \\\"image\\\": {\\\"type\\\": \\\"string\\\", \\\"display\\\": \\\"image\\\" },\\n    \\\"year\\\": {\\\"type\\\": \\\"integer\\\", \\\"store\\\": true },\\n    \\\"votes\\\": {\\\"type\\\": \\\"integer\\\", \\\"store\\\": true },\\n    \\\"director\\\": {\\\"type\\\": \\\"string\\\", \\\"index\\\": \\\"not_analyzed\\\", \\\"store\\\": true },\\n    \\\"actors\\\": {\\\"type\\\": \\\"string\\\", \\\"index\\\": \\\"not_analyzed\\\", \\\"display\\\": \\\"array\\\", \\\"store\\\": true },\\n    \\\"tags\\\": {\\\"type\\\": \\\"string\\\", \\\"display\\\": \\\"array\\\", \\\"store\\\": true },\\n    \\\"rating\\\": {\\\"type\\\": \\\"float\\\", \\\"store\\\": true }\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"`\\\"index\\\": \\\"not_analyzed\\\"` - used mostly when you create term aggregation (string) and want to keep values in the same way as they were inserted\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"`display` (image or array) parameter in field is not compatible with elasticsearch and will be moved to `extraSchema`\"\n}\n[/block]","excerpt":"","category":"5652d741a3de712b00d176dc","githubsync":"","isReference":false,"order":3,"parentDoc":null,"title":"Schema","api":{"auth":"required","params":[],"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"version":"5652d740a3de712b00d176db","createdAt":"2016-05-13T10:47:52.231Z","project":"5652d740a3de712b00d176d8","childrenPages":[]}

Schema

Schema is responsible for fields types and how fields are `stored` and `searched` Schema is compatible with elasticsearch schema (https://www.elastic.co/guide/en/elasticsearch/reference/1.7/mapping-core-types.html) [block:code] { "codes": [ { "code": "\"schema\": {\n \"name\": {\"type\": \"string\", \"store\": true },\n \"image\": {\"type\": \"string\", \"display\": \"image\" },\n \"year\": {\"type\": \"integer\", \"store\": true },\n \"votes\": {\"type\": \"integer\", \"store\": true },\n \"director\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"store\": true },\n \"actors\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"display\": \"array\", \"store\": true },\n \"tags\": {\"type\": \"string\", \"display\": \"array\", \"store\": true },\n \"rating\": {\"type\": \"float\", \"store\": true }\n}\n", "language": "json" } ] } [/block] [block:callout] { "type": "info", "body": "`\"index\": \"not_analyzed\"` - used mostly when you create term aggregation (string) and want to keep values in the same way as they were inserted" } [/block] [block:callout] { "type": "warning", "body": "`display` (image or array) parameter in field is not compatible with elasticsearch and will be moved to `extraSchema`" } [/block]
Schema is responsible for fields types and how fields are `stored` and `searched` Schema is compatible with elasticsearch schema (https://www.elastic.co/guide/en/elasticsearch/reference/1.7/mapping-core-types.html) [block:code] { "codes": [ { "code": "\"schema\": {\n \"name\": {\"type\": \"string\", \"store\": true },\n \"image\": {\"type\": \"string\", \"display\": \"image\" },\n \"year\": {\"type\": \"integer\", \"store\": true },\n \"votes\": {\"type\": \"integer\", \"store\": true },\n \"director\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"store\": true },\n \"actors\": {\"type\": \"string\", \"index\": \"not_analyzed\", \"display\": \"array\", \"store\": true },\n \"tags\": {\"type\": \"string\", \"display\": \"array\", \"store\": true },\n \"rating\": {\"type\": \"float\", \"store\": true }\n}\n", "language": "json" } ] } [/block] [block:callout] { "type": "info", "body": "`\"index\": \"not_analyzed\"` - used mostly when you create term aggregation (string) and want to keep values in the same way as they were inserted" } [/block] [block:callout] { "type": "warning", "body": "`display` (image or array) parameter in field is not compatible with elasticsearch and will be moved to `extraSchema`" } [/block]
{"_id":"5735b32f4b0ab120000b7dc1","api":{"url":"","auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":""},"link_url":"","slug":"extra-schema","title":"Extra schema","user":"5652d72cfab156210023d20a","body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This feature is still in design & development process!\"\n}\n[/block]\nExtra schema is somehow similar to `schema` but it contains extra features and fields and are not directly compatible with elasticsearch\n\nOne of the  first field in `extraSchema` configuration is `enabled`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"extraSchema\\\": {\\n    \\\"enabled\\\": {\\n        \\\"default\\\": true\\n    }\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nIf you make this feature active then all items which you add will have additional `enabled` field with `your` or `default value` (from conf)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"/api/v1/items/:collection/:id/enable\\\" - enable item\\ni.e. \\\"/api/v1/items/movies/10/enable\\\" \\n\\\"/api/v1/items/:collection/:id/disable\\\" - disable item\\n\\\"/api/v1/items/:collection\\\" - search all items \\n\\\"/api/v1/items/:collection?enabled=true\\\" - search through all enabled items \\n\\\"/api/v1/items/:collection?enabled=false\\\" - search through all disabled items \",\n      \"language\": \"shell\",\n      \"name\": \"Rest API examples\"\n    }\n  ]\n}\n[/block]\nUse cases:\n  * items waiting for activation\n  * archiving items\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Plans\",\n  \"body\": \"In the future we are planning to add more custom fields like `array` or `image` (i.e. with S3 integration) or maybe fields like `likes` or `visited` for recommendation purposes\"\n}\n[/block]","category":"5652d741a3de712b00d176dc","githubsync":"","isReference":false,"order":4,"parentDoc":null,"project":"5652d740a3de712b00d176d8","__v":13,"hidden":false,"updates":[],"createdAt":"2016-05-13T10:57:51.479Z","excerpt":"","link_external":false,"sync_unique":"","type":"basic","version":"5652d740a3de712b00d176db","childrenPages":[]}

Extra schema

[block:callout] { "type": "warning", "body": "This feature is still in design & development process!" } [/block] Extra schema is somehow similar to `schema` but it contains extra features and fields and are not directly compatible with elasticsearch One of the first field in `extraSchema` configuration is `enabled` [block:code] { "codes": [ { "code": "\"extraSchema\": {\n \"enabled\": {\n \"default\": true\n }\n}\n", "language": "json" } ] } [/block] If you make this feature active then all items which you add will have additional `enabled` field with `your` or `default value` (from conf) [block:code] { "codes": [ { "code": "\"/api/v1/items/:collection/:id/enable\" - enable item\ni.e. \"/api/v1/items/movies/10/enable\" \n\"/api/v1/items/:collection/:id/disable\" - disable item\n\"/api/v1/items/:collection\" - search all items \n\"/api/v1/items/:collection?enabled=true\" - search through all enabled items \n\"/api/v1/items/:collection?enabled=false\" - search through all disabled items ", "language": "shell", "name": "Rest API examples" } ] } [/block] Use cases: * items waiting for activation * archiving items [block:callout] { "type": "info", "title": "Plans", "body": "In the future we are planning to add more custom fields like `array` or `image` (i.e. with S3 integration) or maybe fields like `likes` or `visited` for recommendation purposes" } [/block]
[block:callout] { "type": "warning", "body": "This feature is still in design & development process!" } [/block] Extra schema is somehow similar to `schema` but it contains extra features and fields and are not directly compatible with elasticsearch One of the first field in `extraSchema` configuration is `enabled` [block:code] { "codes": [ { "code": "\"extraSchema\": {\n \"enabled\": {\n \"default\": true\n }\n}\n", "language": "json" } ] } [/block] If you make this feature active then all items which you add will have additional `enabled` field with `your` or `default value` (from conf) [block:code] { "codes": [ { "code": "\"/api/v1/items/:collection/:id/enable\" - enable item\ni.e. \"/api/v1/items/movies/10/enable\" \n\"/api/v1/items/:collection/:id/disable\" - disable item\n\"/api/v1/items/:collection\" - search all items \n\"/api/v1/items/:collection?enabled=true\" - search through all enabled items \n\"/api/v1/items/:collection?enabled=false\" - search through all disabled items ", "language": "shell", "name": "Rest API examples" } ] } [/block] Use cases: * items waiting for activation * archiving items [block:callout] { "type": "info", "title": "Plans", "body": "In the future we are planning to add more custom fields like `array` or `image` (i.e. with S3 integration) or maybe fields like `likes` or `visited` for recommendation purposes" } [/block]
{"_id":"572a0989d10a200e00b1ca62","link_external":false,"sync_unique":"","version":"5652d740a3de712b00d176db","body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Terms aggregation\"\n}\n[/block]\n`Facets` / `filters` / `aggregations`  is one of the powerful feature of ItemsAPI and work almost completely out of the box. It is a way to filter items to get more narrow and precise results.\n\nThere are few type of aggregations. The first one is the simplest `terms`. The field for `terms` be string (i.e. some country) or  array (i.e. list of tags)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"schema\\\": {\\n        \\\"country\\\": {\\n            \\\"type\\\": \\\"string\\\",\\n            \\\"index\\\": \\\"not_analyzed\\\",\\n            \\\"store\\\": true\\n        }\\n    },\\n    \\\"aggregations\\\": {\\n        \\\"country\\\": {\\n            \\\"type\\\": \\\"terms\\\",\\n            \\\"field\\\": \\\"country\\\",\\n            \\\"size\\\": 10,\\n            \\\"conjunction\\\": true,\\n            \\\"title\\\": \\\"Country\\\"\\n        }\\n    }\\n}\\n\",\n      \"language\": \"javascript\",\n      \"name\": \"part of collection conf\"\n    }\n  ]\n}\n[/block]\nIt looks like:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/5BIO5nPR1K6IWOyx3wO0_Selection_263.jpg\",\n        \"Selection_263.jpg\",\n        \"270\",\n        \"240\",\n        \"#72889c\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nSorting terms aggregation:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"schema\\\": {\\n        \\\"country\\\": {\\n            \\\"type\\\": \\\"string\\\",\\n            \\\"index\\\": \\\"not_analyzed\\\",\\n            \\\"store\\\": true\\n        }\\n    },\\n    \\\"aggregations\\\": {\\n        \\\"country\\\": {\\n            \\\"type\\\": \\\"terms\\\",\\n            \\\"field\\\": \\\"country\\\",\\n            \\\"size\\\": 10,\\n            \\\"title\\\": \\\"Country\\\",\\n\\t\\t\\t\\t\\t\\t\\\"sort\\\": \\\"_term\\\",\\n\\t\\t\\t\\t\\t\\t\\\"order\\\": \\\"asc\\\"\\n        }\\n    }\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Sorting options\",\n  \"body\": \"\\\"sort\\\" can be \\\"_term\\\" or \\\"_count\\\" and \\\"order\\\": \\\"asc\\\" or \\\"desc\\\"\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Geo distance aggregation\"\n}\n[/block]\nNext type of aggregation is `geo_distance`. It show filter of distance ranges:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"schema\\\": {\\n        \\\"geo\\\": {\\n            \\\"type\\\": \\\"geo_point\\\"\\n        }\\n    },\\n    \\\"aggregations\\\": {\\n        \\\"distance_ranges\\\": {\\n            \\\"type\\\": \\\"geo_distance\\\",\\n            \\\"field\\\": \\\"geo\\\",\\n            \\\"ranges\\\": [\\n                {\\n                    \\\"lte\\\": 500,\\n                    \\\"name\\\": \\\"< 500\\\"\\n                },\\n                {\\n                    \\\"gte\\\": 500,\\n                    \\\"lte\\\": 1000,\\n                    \\\"name\\\": \\\"500 - 1000\\\"\\n                },\\n                {\\n                    \\\"gte\\\": 500,\\n                    \\\"name\\\": \\\"> 1000\\\"\\n                }\\n            ],\\n            \\\"unit\\\": \\\"km\\\",\\n            \\\"title\\\": \\\"Distance ranges [km]\\\"\\n        }\\n    }\\n}\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/9PbyxfCERs6qPbpcKybz_Selection_264.jpg\",\n        \"Selection_264.jpg\",\n        \"204\",\n        \"105\",\n        \"#ebebf2\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Range aggregation\"\n}\n[/block]\nNext example is `range` aggregation. Great for ratings, votes ranges and just for different ranges:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"schema\\\": {\\n        \\\"rating\\\": {\\n            \\\"type\\\": \\\"float\\\"\\n        }\\n    },\\n    \\\"aggregations\\\": {\\n        \\\"ratings\\\": {\\n            \\\"type\\\": \\\"range\\\",\\n            \\\"field\\\": \\\"rating\\\",\\n            \\\"title\\\": \\\"Rating\\\",\\n            \\\"ranges\\\": [\\n                {\\n                    \\\"lte\\\": 1,\\n                    \\\"name\\\": \\\"0 - 1\\\"\\n                },\\n                {\\n                    \\\"gte\\\": 1,\\n                    \\\"lte\\\": 2,\\n                    \\\"name\\\": \\\"1 - 2\\\"\\n                },\\n                {\\n                    \\\"gte\\\": 2,\\n                    \\\"lte\\\": 3,\\n                    \\\"name\\\": \\\"2 - 3\\\"\\n                },\\n                {\\n                    \\\"gte\\\": 3,\\n                    \\\"lte\\\": 4,\\n                    \\\"name\\\": \\\"3 - 4\\\"\\n                },\\n                {\\n                    \\\"gte\\\": 4,\\n                    \\\"lte\\\": 5,\\n                    \\\"name\\\": \\\"4 - 5\\\"\\n                },\\n                {\\n                    \\\"gte\\\": 4,\\n                    \\\"name\\\": \\\"4 - 5\\\"\\n                }\\n            ]\\n        }\\n    }\\n}\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/lTHwgjDbRiKegBjScvlv_Selection_265.jpg\",\n        \"Selection_265.jpg\",\n        \"189\",\n        \"123\",\n        \"#ebecf3\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"From 1.0.13 version is possible to store aggregations options as an array too.\",\n  \"title\": \"aggregations options as an array\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Storing aggregations as array\",\n  \"body\": \"That implementation was an mistake because additional choices are usually bad from UX point and it is much harder to maintain such a software.\\n\\nPlease store your aggregations as an object and not as an array!\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/P38xrRA3TgOJsw5UH2tz_Selection_249.jpg\",\n        \"Selection_249.jpg\",\n        \"255\",\n        \"405\",\n        \"#5c90be\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nThe example response of aggregation in json search response looks like:","createdAt":"2016-05-04T14:39:05.717Z","excerpt":"","githubsync":"","hidden":false,"link_url":"","parentDoc":null,"project":"5652d740a3de712b00d176d8","api":{"settings":"","url":"","auth":"required","params":[],"results":{"codes":[{"name":"","status":200,"language":"json","code":"{}"},{"status":400,"language":"json","code":"{}","name":""}]}},"updates":[],"isReference":false,"order":5,"slug":"facets-filters","title":"Facets / aggregations","user":"5652d72cfab156210023d20a","__v":11,"category":"5652d741a3de712b00d176dc","next":{"description":"","pages":[]},"type":"basic","childrenPages":[]}

Facets / aggregations

[block:api-header] { "type": "basic", "title": "Terms aggregation" } [/block] `Facets` / `filters` / `aggregations` is one of the powerful feature of ItemsAPI and work almost completely out of the box. It is a way to filter items to get more narrow and precise results. There are few type of aggregations. The first one is the simplest `terms`. The field for `terms` be string (i.e. some country) or array (i.e. list of tags) [block:code] { "codes": [ { "code": "{\n \"schema\": {\n \"country\": {\n \"type\": \"string\",\n \"index\": \"not_analyzed\",\n \"store\": true\n }\n },\n \"aggregations\": {\n \"country\": {\n \"type\": \"terms\",\n \"field\": \"country\",\n \"size\": 10,\n \"conjunction\": true,\n \"title\": \"Country\"\n }\n }\n}\n", "language": "javascript", "name": "part of collection conf" } ] } [/block] It looks like: [block:image] { "images": [ { "image": [ "https://files.readme.io/5BIO5nPR1K6IWOyx3wO0_Selection_263.jpg", "Selection_263.jpg", "270", "240", "#72889c", "" ] } ] } [/block] Sorting terms aggregation: [block:code] { "codes": [ { "code": "{\n \"schema\": {\n \"country\": {\n \"type\": \"string\",\n \"index\": \"not_analyzed\",\n \"store\": true\n }\n },\n \"aggregations\": {\n \"country\": {\n \"type\": \"terms\",\n \"field\": \"country\",\n \"size\": 10,\n \"title\": \"Country\",\n\t\t\t\t\t\t\"sort\": \"_term\",\n\t\t\t\t\t\t\"order\": \"asc\"\n }\n }\n}\n", "language": "json" } ] } [/block] [block:callout] { "type": "info", "title": "Sorting options", "body": "\"sort\" can be \"_term\" or \"_count\" and \"order\": \"asc\" or \"desc\"" } [/block] [block:api-header] { "type": "basic", "title": "Geo distance aggregation" } [/block] Next type of aggregation is `geo_distance`. It show filter of distance ranges: [block:code] { "codes": [ { "code": "{\n \"schema\": {\n \"geo\": {\n \"type\": \"geo_point\"\n }\n },\n \"aggregations\": {\n \"distance_ranges\": {\n \"type\": \"geo_distance\",\n \"field\": \"geo\",\n \"ranges\": [\n {\n \"lte\": 500,\n \"name\": \"< 500\"\n },\n {\n \"gte\": 500,\n \"lte\": 1000,\n \"name\": \"500 - 1000\"\n },\n {\n \"gte\": 500,\n \"name\": \"> 1000\"\n }\n ],\n \"unit\": \"km\",\n \"title\": \"Distance ranges [km]\"\n }\n }\n}\n", "language": "javascript" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/9PbyxfCERs6qPbpcKybz_Selection_264.jpg", "Selection_264.jpg", "204", "105", "#ebebf2", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Range aggregation" } [/block] Next example is `range` aggregation. Great for ratings, votes ranges and just for different ranges: [block:code] { "codes": [ { "code": "{\n \"schema\": {\n \"rating\": {\n \"type\": \"float\"\n }\n },\n \"aggregations\": {\n \"ratings\": {\n \"type\": \"range\",\n \"field\": \"rating\",\n \"title\": \"Rating\",\n \"ranges\": [\n {\n \"lte\": 1,\n \"name\": \"0 - 1\"\n },\n {\n \"gte\": 1,\n \"lte\": 2,\n \"name\": \"1 - 2\"\n },\n {\n \"gte\": 2,\n \"lte\": 3,\n \"name\": \"2 - 3\"\n },\n {\n \"gte\": 3,\n \"lte\": 4,\n \"name\": \"3 - 4\"\n },\n {\n \"gte\": 4,\n \"lte\": 5,\n \"name\": \"4 - 5\"\n },\n {\n \"gte\": 4,\n \"name\": \"4 - 5\"\n }\n ]\n }\n }\n}\n", "language": "javascript" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/lTHwgjDbRiKegBjScvlv_Selection_265.jpg", "Selection_265.jpg", "189", "123", "#ebecf3", "" ] } ] } [/block] [block:callout] { "type": "info", "body": "From 1.0.13 version is possible to store aggregations options as an array too.", "title": "aggregations options as an array" } [/block] [block:callout] { "type": "danger", "title": "Storing aggregations as array", "body": "That implementation was an mistake because additional choices are usually bad from UX point and it is much harder to maintain such a software.\n\nPlease store your aggregations as an object and not as an array!" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/P38xrRA3TgOJsw5UH2tz_Selection_249.jpg", "Selection_249.jpg", "255", "405", "#5c90be", "" ] } ] } [/block] The example response of aggregation in json search response looks like:
[block:api-header] { "type": "basic", "title": "Terms aggregation" } [/block] `Facets` / `filters` / `aggregations` is one of the powerful feature of ItemsAPI and work almost completely out of the box. It is a way to filter items to get more narrow and precise results. There are few type of aggregations. The first one is the simplest `terms`. The field for `terms` be string (i.e. some country) or array (i.e. list of tags) [block:code] { "codes": [ { "code": "{\n \"schema\": {\n \"country\": {\n \"type\": \"string\",\n \"index\": \"not_analyzed\",\n \"store\": true\n }\n },\n \"aggregations\": {\n \"country\": {\n \"type\": \"terms\",\n \"field\": \"country\",\n \"size\": 10,\n \"conjunction\": true,\n \"title\": \"Country\"\n }\n }\n}\n", "language": "javascript", "name": "part of collection conf" } ] } [/block] It looks like: [block:image] { "images": [ { "image": [ "https://files.readme.io/5BIO5nPR1K6IWOyx3wO0_Selection_263.jpg", "Selection_263.jpg", "270", "240", "#72889c", "" ] } ] } [/block] Sorting terms aggregation: [block:code] { "codes": [ { "code": "{\n \"schema\": {\n \"country\": {\n \"type\": \"string\",\n \"index\": \"not_analyzed\",\n \"store\": true\n }\n },\n \"aggregations\": {\n \"country\": {\n \"type\": \"terms\",\n \"field\": \"country\",\n \"size\": 10,\n \"title\": \"Country\",\n\t\t\t\t\t\t\"sort\": \"_term\",\n\t\t\t\t\t\t\"order\": \"asc\"\n }\n }\n}\n", "language": "json" } ] } [/block] [block:callout] { "type": "info", "title": "Sorting options", "body": "\"sort\" can be \"_term\" or \"_count\" and \"order\": \"asc\" or \"desc\"" } [/block] [block:api-header] { "type": "basic", "title": "Geo distance aggregation" } [/block] Next type of aggregation is `geo_distance`. It show filter of distance ranges: [block:code] { "codes": [ { "code": "{\n \"schema\": {\n \"geo\": {\n \"type\": \"geo_point\"\n }\n },\n \"aggregations\": {\n \"distance_ranges\": {\n \"type\": \"geo_distance\",\n \"field\": \"geo\",\n \"ranges\": [\n {\n \"lte\": 500,\n \"name\": \"< 500\"\n },\n {\n \"gte\": 500,\n \"lte\": 1000,\n \"name\": \"500 - 1000\"\n },\n {\n \"gte\": 500,\n \"name\": \"> 1000\"\n }\n ],\n \"unit\": \"km\",\n \"title\": \"Distance ranges [km]\"\n }\n }\n}\n", "language": "javascript" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/9PbyxfCERs6qPbpcKybz_Selection_264.jpg", "Selection_264.jpg", "204", "105", "#ebebf2", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Range aggregation" } [/block] Next example is `range` aggregation. Great for ratings, votes ranges and just for different ranges: [block:code] { "codes": [ { "code": "{\n \"schema\": {\n \"rating\": {\n \"type\": \"float\"\n }\n },\n \"aggregations\": {\n \"ratings\": {\n \"type\": \"range\",\n \"field\": \"rating\",\n \"title\": \"Rating\",\n \"ranges\": [\n {\n \"lte\": 1,\n \"name\": \"0 - 1\"\n },\n {\n \"gte\": 1,\n \"lte\": 2,\n \"name\": \"1 - 2\"\n },\n {\n \"gte\": 2,\n \"lte\": 3,\n \"name\": \"2 - 3\"\n },\n {\n \"gte\": 3,\n \"lte\": 4,\n \"name\": \"3 - 4\"\n },\n {\n \"gte\": 4,\n \"lte\": 5,\n \"name\": \"4 - 5\"\n },\n {\n \"gte\": 4,\n \"name\": \"4 - 5\"\n }\n ]\n }\n }\n}\n", "language": "javascript" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/lTHwgjDbRiKegBjScvlv_Selection_265.jpg", "Selection_265.jpg", "189", "123", "#ebecf3", "" ] } ] } [/block] [block:callout] { "type": "info", "body": "From 1.0.13 version is possible to store aggregations options as an array too.", "title": "aggregations options as an array" } [/block] [block:callout] { "type": "danger", "title": "Storing aggregations as array", "body": "That implementation was an mistake because additional choices are usually bad from UX point and it is much harder to maintain such a software.\n\nPlease store your aggregations as an object and not as an array!" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/P38xrRA3TgOJsw5UH2tz_Selection_249.jpg", "Selection_249.jpg", "255", "405", "#5c90be", "" ] } ] } [/block] The example response of aggregation in json search response looks like:
{"_id":"57272cd855e8ec0e00402774","category":"5652d741a3de712b00d176dc","createdAt":"2016-05-02T10:32:56.223Z","project":"5652d740a3de712b00d176d8","slug":"sorting","type":"basic","body":"Below is example of sorting configuration:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"defaults\\\": {\\n    \\\"sort\\\": \\\"most_votes\\\"\\n},\\n\\\"sortings\\\": {\\n    \\\"most_votes\\\": {\\n        \\\"title\\\": \\\"Most votes\\\",\\n        \\\"type\\\": \\\"normal\\\",\\n        \\\"order\\\": \\\"desc\\\",\\n        \\\"field\\\": \\\"votes\\\"\\n    },\\n    \\\"nearest_hotels\\\": {\\n        \\\"title\\\": \\\"Nearest locations\\\",\\n        \\\"type\\\": \\\"geo\\\",\\n        \\\"order\\\": \\\"asc\\\",\\n        \\\"field\\\": \\\"geo\\\"\\n    }\\n}\\n\",\n      \"language\": \"javascript\",\n      \"name\": \"sorting example configuration\"\n    }\n  ]\n}\n[/block]\nYou need to provide sort key if you want to sort items i.e. `/api/v1/cities?sort=nearest_hotels`. If you don't provide sort key it will take default one `most_votes`\n\nIf you don't provide defaults sort it will make default elasticsearch sorting\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/HvEOeSBzQ7KPtcc4PrpK_Selection_259.jpg\",\n        \"Selection_259.jpg\",\n        \"518\",\n        \"405\",\n        \"#647c94\",\n        \"\"\n      ],\n      \"caption\": \"The default part of search response looks like above\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Sorting by multiple fields\",\n  \"body\": \"Since ItemsAPI 1.0.52 version it is possible to sort by multiple fields. Below is an example.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"sortings\\\": {\\n  \\\"mix\\\": {\\n    \\\"title\\\": \\\"Rating\\\",\\n    \\\"sort\\\": [\\n      {\\n        \\\"name\\\": {\\n          \\\"order\\\": \\\"asc\\\"\\n        }\\n      },\\n      {\\n        \\\"rating\\\": {\\n          \\\"order\\\": \\\"desc\\\"\\n        }\\n      }\\n    ]\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nIt doesn't have `type`, `order` and `field` fields but only `sort` and works in the same way as in Elasticsearch https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-sort.html","githubsync":"","title":"Sorting","updates":[],"__v":1,"excerpt":"How to sort items","hidden":false,"isReference":false,"order":6,"sync_unique":"","user":"5652d72cfab156210023d20a","api":{"settings":"","url":"","auth":"required","params":[],"results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"name":"","status":400,"language":"json","code":"{}"}]}},"link_external":false,"link_url":"","parentDoc":null,"version":"5652d740a3de712b00d176db","childrenPages":[]}

Sorting

How to sort items
Below is example of sorting configuration: [block:code] { "codes": [ { "code": "\"defaults\": {\n \"sort\": \"most_votes\"\n},\n\"sortings\": {\n \"most_votes\": {\n \"title\": \"Most votes\",\n \"type\": \"normal\",\n \"order\": \"desc\",\n \"field\": \"votes\"\n },\n \"nearest_hotels\": {\n \"title\": \"Nearest locations\",\n \"type\": \"geo\",\n \"order\": \"asc\",\n \"field\": \"geo\"\n }\n}\n", "language": "javascript", "name": "sorting example configuration" } ] } [/block] You need to provide sort key if you want to sort items i.e. `/api/v1/cities?sort=nearest_hotels`. If you don't provide sort key it will take default one `most_votes` If you don't provide defaults sort it will make default elasticsearch sorting [block:image] { "images": [ { "image": [ "https://files.readme.io/HvEOeSBzQ7KPtcc4PrpK_Selection_259.jpg", "Selection_259.jpg", "518", "405", "#647c94", "" ], "caption": "The default part of search response looks like above" } ] } [/block] [block:callout] { "type": "info", "title": "Sorting by multiple fields", "body": "Since ItemsAPI 1.0.52 version it is possible to sort by multiple fields. Below is an example." } [/block] [block:code] { "codes": [ { "code": "\"sortings\": {\n \"mix\": {\n \"title\": \"Rating\",\n \"sort\": [\n {\n \"name\": {\n \"order\": \"asc\"\n }\n },\n {\n \"rating\": {\n \"order\": \"desc\"\n }\n }\n ]\n }\n}", "language": "json" } ] } [/block] It doesn't have `type`, `order` and `field` fields but only `sort` and works in the same way as in Elasticsearch https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-sort.html
Below is example of sorting configuration: [block:code] { "codes": [ { "code": "\"defaults\": {\n \"sort\": \"most_votes\"\n},\n\"sortings\": {\n \"most_votes\": {\n \"title\": \"Most votes\",\n \"type\": \"normal\",\n \"order\": \"desc\",\n \"field\": \"votes\"\n },\n \"nearest_hotels\": {\n \"title\": \"Nearest locations\",\n \"type\": \"geo\",\n \"order\": \"asc\",\n \"field\": \"geo\"\n }\n}\n", "language": "javascript", "name": "sorting example configuration" } ] } [/block] You need to provide sort key if you want to sort items i.e. `/api/v1/cities?sort=nearest_hotels`. If you don't provide sort key it will take default one `most_votes` If you don't provide defaults sort it will make default elasticsearch sorting [block:image] { "images": [ { "image": [ "https://files.readme.io/HvEOeSBzQ7KPtcc4PrpK_Selection_259.jpg", "Selection_259.jpg", "518", "405", "#647c94", "" ], "caption": "The default part of search response looks like above" } ] } [/block] [block:callout] { "type": "info", "title": "Sorting by multiple fields", "body": "Since ItemsAPI 1.0.52 version it is possible to sort by multiple fields. Below is an example." } [/block] [block:code] { "codes": [ { "code": "\"sortings\": {\n \"mix\": {\n \"title\": \"Rating\",\n \"sort\": [\n {\n \"name\": {\n \"order\": \"asc\"\n }\n },\n {\n \"rating\": {\n \"order\": \"desc\"\n }\n }\n ]\n }\n}", "language": "json" } ] } [/block] It doesn't have `type`, `order` and `field` fields but only `sort` and works in the same way as in Elasticsearch https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-sort.html
{"_id":"5735ce3f4b0ab120000b7dfb","user":"5652d72cfab156210023d20a","version":"5652d740a3de712b00d176db","category":"5652d741a3de712b00d176dc","link_external":false,"slug":"breadcrumbs","type":"basic","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Breadcrumbs are possible to do with search and facets / aggregations. Code example soon!\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/jQb6lQOlSbKQJVb5vR5w_Selection_305.jpg\",\n        \"Selection_305.jpg\",\n        \"250\",\n        \"63\",\n        \"#e7e6e1\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]","link_url":"","sync_unique":"","title":"Breadcrumbs","updates":[],"__v":0,"excerpt":"","githubsync":"","hidden":false,"project":"5652d740a3de712b00d176d8","createdAt":"2016-05-13T12:53:19.381Z","isReference":false,"order":7,"parentDoc":null,"childrenPages":[]}

Breadcrumbs

[block:callout] { "type": "info", "body": "Breadcrumbs are possible to do with search and facets / aggregations. Code example soon!" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/jQb6lQOlSbKQJVb5vR5w_Selection_305.jpg", "Selection_305.jpg", "250", "63", "#e7e6e1", "" ] } ] } [/block]
[block:callout] { "type": "info", "body": "Breadcrumbs are possible to do with search and facets / aggregations. Code example soon!" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/jQb6lQOlSbKQJVb5vR5w_Selection_305.jpg", "Selection_305.jpg", "250", "63", "#e7e6e1", "" ] } ] } [/block]
{"_id":"5652f78a87078e2300e28666","body":"Be sure that you have mocha and grunt installed. \n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Global package installation\",\n  \"body\": \"Often to require sudo permission, `$ sudo npm install mocha -g`\"\n}\n[/block]\n```\n$ sudo npm install mocha -g\n$ sudo npm install grunt-cli -g\n```\n\nTo run all tests:\n```\n$ grunt test\n```\n\nTo run specific test:\n```\n$ mocha tests/services/searchSpec.js\n```","createdAt":"2015-11-23T11:24:58.334Z","link_external":false,"project":"5652d740a3de712b00d176d8","sync_unique":"","type":"basic","user":"5652d72cfab156210023d20a","githubsync":"","hidden":false,"link_url":"","parentDoc":null,"title":"Testing","slug":"testing","updates":["565cd829b311ea0d00a383e0"],"api":{"url":"","auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"language":"json","code":"{}","name":"","status":400}]},"settings":""},"category":"5652d741a3de712b00d176dc","excerpt":"Well tested software allows for better sleep","isReference":false,"__v":3,"order":9,"version":"5652d740a3de712b00d176db","childrenPages":[]}

Testing

Well tested software allows for better sleep
Be sure that you have mocha and grunt installed. [block:callout] { "type": "info", "title": "Global package installation", "body": "Often to require sudo permission, `$ sudo npm install mocha -g`" } [/block] ``` $ sudo npm install mocha -g $ sudo npm install grunt-cli -g ``` To run all tests: ``` $ grunt test ``` To run specific test: ``` $ mocha tests/services/searchSpec.js ```
Be sure that you have mocha and grunt installed. [block:callout] { "type": "info", "title": "Global package installation", "body": "Often to require sudo permission, `$ sudo npm install mocha -g`" } [/block] ``` $ sudo npm install mocha -g $ sudo npm install grunt-cli -g ``` To run all tests: ``` $ grunt test ``` To run specific test: ``` $ mocha tests/services/searchSpec.js ```
{"_id":"56545168ec18923500296780","type":"basic","githubsync":"","hidden":false,"project":"5652d740a3de712b00d176d8","excerpt":"One demo sometimes tells more than 1000 words","api":{"settings":"","url":"","auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]}},"body":"http://app.itemsapi.com (list of collections)\n\nExample collections:\n- [Movies](http://app.itemsapi.com/documents/name/movie \"Movies\")\n- [Songs](http://app.itemsapi.com/documents/name/song \"Songs\")\n- [Quotes](http://app.itemsapi.com/documents/name/quote \"Quotes\")\n- [NPM libraries](http://app.itemsapi.com/documents/name/npm \"NPM libraries\")","createdAt":"2015-11-24T12:00:40.924Z","order":10,"title":"Demo","user":"5652d72cfab156210023d20a","version":"5652d740a3de712b00d176db","category":"5652d741a3de712b00d176dc","isReference":false,"link_external":false,"parentDoc":null,"slug":"demo","sync_unique":"","updates":[],"__v":1,"link_url":"","childrenPages":[]}

Demo

One demo sometimes tells more than 1000 words
http://app.itemsapi.com (list of collections) Example collections: - [Movies](http://app.itemsapi.com/documents/name/movie "Movies") - [Songs](http://app.itemsapi.com/documents/name/song "Songs") - [Quotes](http://app.itemsapi.com/documents/name/quote "Quotes") - [NPM libraries](http://app.itemsapi.com/documents/name/npm "NPM libraries")
http://app.itemsapi.com (list of collections) Example collections: - [Movies](http://app.itemsapi.com/documents/name/movie "Movies") - [Songs](http://app.itemsapi.com/documents/name/song "Songs") - [Quotes](http://app.itemsapi.com/documents/name/quote "Quotes") - [NPM libraries](http://app.itemsapi.com/documents/name/npm "NPM libraries")
{"_id":"566154d589e82f0d008f6869","hidden":false,"isReference":false,"link_url":"","project":"5652d740a3de712b00d176d8","slug":"cli","sync_unique":"","title":"CLI","category":"5652d741a3de712b00d176dc","link_external":false,"type":"basic","__v":18,"api":{"settings":"","url":"","auth":"required","params":[],"results":{"codes":[{"name":"","status":200,"language":"json","code":"{}"},{"language":"json","code":"{}","name":"","status":400}]}},"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"ItemsAPI\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"As there are a few ways to install and run itemsapi CLI sometimes can not work as expected. \\nThere is a plan to make separate, dedicated repo for itemsapi i.e. itemsapi-cli.\\n\\nIt will provide some useful tools for managing project, statistics, reindexing and maybe even as a project creator\"\n}\n[/block]\nConsole is very useful function in most successful frameworks like symfony2, meteor.js, ionicframework.\n\nImporting big or small json data to your defined collection: \n```\n$ node cli.js --import --collection=movie --file ./data/fixtures/movies.json\n```\n\nExporting itemsapi collection to `./data/exports/collection.json`\n```\n$ node cli.js --export --collection=movie --project=mycollections`\n```\n\nClear collection items:\n``` bash\n$ node cli.js --clear --collection=movie --project=mycollections\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Elasticsearch\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"All those methods will make operations on elasticsearch configured in  `config/local.json` or `config/root.json`\",\n  \"title\": \"Elasticsearch url\"\n}\n[/block]\nTo show all elasticsearch indices\n```\n$ node cli.js --elasticsearch --indices\n```\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/KsEsOAi2SACmWimloY4D_Selection_374.png\",\n        \"Selection_374.png\",\n        \"679\",\n        \"95\",\n        \"#893f16\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nShow elasticsearch mappings (type and index is optional)\n```\n$ node cli.js --elasticsearch --mapping --type=city --index=project\n```\n\nImport specific type to the local collections db\n`type` and `index` are optional (it will take first mapping)\n```\n$ node cli.js --elasticsearch --import --type=movie --index=project\n```","excerpt":"Useful command line functionalities","githubsync":"","parentDoc":null,"version":"5652d740a3de712b00d176db","createdAt":"2015-12-04T08:54:45.955Z","order":11,"updates":["5661a2b5bb77350d00732659"],"user":"5652d72cfab156210023d20a","childrenPages":[]}

CLI

Useful command line functionalities
[block:api-header] { "type": "basic", "title": "ItemsAPI" } [/block] [block:callout] { "type": "danger", "body": "As there are a few ways to install and run itemsapi CLI sometimes can not work as expected. \nThere is a plan to make separate, dedicated repo for itemsapi i.e. itemsapi-cli.\n\nIt will provide some useful tools for managing project, statistics, reindexing and maybe even as a project creator" } [/block] Console is very useful function in most successful frameworks like symfony2, meteor.js, ionicframework. Importing big or small json data to your defined collection: ``` $ node cli.js --import --collection=movie --file ./data/fixtures/movies.json ``` Exporting itemsapi collection to `./data/exports/collection.json` ``` $ node cli.js --export --collection=movie --project=mycollections` ``` Clear collection items: ``` bash $ node cli.js --clear --collection=movie --project=mycollections ``` [block:api-header] { "type": "basic", "title": "Elasticsearch" } [/block] [block:callout] { "type": "warning", "body": "All those methods will make operations on elasticsearch configured in `config/local.json` or `config/root.json`", "title": "Elasticsearch url" } [/block] To show all elasticsearch indices ``` $ node cli.js --elasticsearch --indices ``` [block:image] { "images": [ { "image": [ "https://files.readme.io/KsEsOAi2SACmWimloY4D_Selection_374.png", "Selection_374.png", "679", "95", "#893f16", "" ] } ] } [/block] Show elasticsearch mappings (type and index is optional) ``` $ node cli.js --elasticsearch --mapping --type=city --index=project ``` Import specific type to the local collections db `type` and `index` are optional (it will take first mapping) ``` $ node cli.js --elasticsearch --import --type=movie --index=project ```
[block:api-header] { "type": "basic", "title": "ItemsAPI" } [/block] [block:callout] { "type": "danger", "body": "As there are a few ways to install and run itemsapi CLI sometimes can not work as expected. \nThere is a plan to make separate, dedicated repo for itemsapi i.e. itemsapi-cli.\n\nIt will provide some useful tools for managing project, statistics, reindexing and maybe even as a project creator" } [/block] Console is very useful function in most successful frameworks like symfony2, meteor.js, ionicframework. Importing big or small json data to your defined collection: ``` $ node cli.js --import --collection=movie --file ./data/fixtures/movies.json ``` Exporting itemsapi collection to `./data/exports/collection.json` ``` $ node cli.js --export --collection=movie --project=mycollections` ``` Clear collection items: ``` bash $ node cli.js --clear --collection=movie --project=mycollections ``` [block:api-header] { "type": "basic", "title": "Elasticsearch" } [/block] [block:callout] { "type": "warning", "body": "All those methods will make operations on elasticsearch configured in `config/local.json` or `config/root.json`", "title": "Elasticsearch url" } [/block] To show all elasticsearch indices ``` $ node cli.js --elasticsearch --indices ``` [block:image] { "images": [ { "image": [ "https://files.readme.io/KsEsOAi2SACmWimloY4D_Selection_374.png", "Selection_374.png", "679", "95", "#893f16", "" ] } ] } [/block] Show elasticsearch mappings (type and index is optional) ``` $ node cli.js --elasticsearch --mapping --type=city --index=project ``` Import specific type to the local collections db `type` and `index` are optional (it will take first mapping) ``` $ node cli.js --elasticsearch --import --type=movie --index=project ```
{"_id":"5730e5f60f929f3600841cff","githubsync":"","project":"5652d740a3de712b00d176d8","updates":[],"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"","auth":"required","params":[]},"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The API endpoints summary in progress. For more detailed info go into `Items API`, `Collections API`, `Collections API Mapping`\"\n}\n[/block]","category":"5652d741a3de712b00d176dc","createdAt":"2016-05-09T19:33:10.712Z","excerpt":"","link_url":"","isReference":false,"order":12,"slug":"rest-endpoints","sync_unique":"","title":"Rest endpoints","type":"basic","user":"5652d72cfab156210023d20a","version":"5652d740a3de712b00d176db","__v":5,"hidden":false,"link_external":false,"parentDoc":null,"childrenPages":[]}

Rest endpoints

[block:callout] { "type": "warning", "body": "The API endpoints summary in progress. For more detailed info go into `Items API`, `Collections API`, `Collections API Mapping`" } [/block]
[block:callout] { "type": "warning", "body": "The API endpoints summary in progress. For more detailed info go into `Items API`, `Collections API`, `Collections API Mapping`" } [/block]
{"_id":"57bd75fc0fe3a00e003e2cae","title":"Security","excerpt":"","githubsync":"","slug":"security","type":"basic","version":"5652d740a3de712b00d176db","__v":0,"api":{"settings":"","auth":"required","params":[],"url":"","results":{"codes":[{"name":"","status":200,"language":"json","code":"{}"},{"status":400,"language":"json","code":"{}","name":""}]}},"sync_unique":"","order":999,"project":"5652d740a3de712b00d176d8","updates":[],"user":"5652d72cfab156210023d20a","category":"5652d741a3de712b00d176dc","isReference":false,"link_external":false,"link_url":"","body":"To secure API queries there is configuration example:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e105d6f-Selection_498.jpg\",\n        \"Selection_498.jpg\",\n        705,\n        266,\n        \"#eee0e3\"\n      ]\n    }\n  ]\n}\n[/block]\n`allowed_methods` can be parameter like: \"*\" or [\"GET\"] or [\"GET\", \"POST\"] etc\n\nToken can be provided as:\n- `token` in get query\n- `token` in body query\n- `x-access-token` in headers","createdAt":"2016-08-24T10:25:00.327Z","hidden":false,"childrenPages":[]}

Security

To secure API queries there is configuration example: [block:image] { "images": [ { "image": [ "https://files.readme.io/e105d6f-Selection_498.jpg", "Selection_498.jpg", 705, 266, "#eee0e3" ] } ] } [/block] `allowed_methods` can be parameter like: "*" or ["GET"] or ["GET", "POST"] etc Token can be provided as: - `token` in get query - `token` in body query - `x-access-token` in headers
To secure API queries there is configuration example: [block:image] { "images": [ { "image": [ "https://files.readme.io/e105d6f-Selection_498.jpg", "Selection_498.jpg", 705, 266, "#eee0e3" ] } ] } [/block] `allowed_methods` can be parameter like: "*" or ["GET"] or ["GET", "POST"] etc Token can be provided as: - `token` in get query - `token` in body query - `x-access-token` in headers
{"_id":"5652f9f151e4e81900bf244c","updates":[],"user":"5652d72cfab156210023d20a","version":"5652d740a3de712b00d176db","body":"","isReference":true,"order":0,"parentDoc":null,"createdAt":"2015-11-23T11:35:13.764Z","excerpt":"get specific item","link_url":"","sync_unique":"","type":"get","__v":16,"hidden":false,"link_external":false,"project":"5652d740a3de712b00d176d8","slug":"get-item","title":"/items/:collection/:id","api":{"params":[],"results":{"codes":[{"code":"{\n  id: 36554,\n  text: \"The secret to getting ahead is getting started.\",\n  image: \"https://d.gr-assets.com/authors/1322103868p2/1244.jpg\",\n  author: \"Mark Twain\",\n  book: \"\",\n  tags: [\n    \"starting\",\n    \"working\"\n  ],\n  likes: 1852\n}","name":"","status":200,"language":"json"},{"status":400,"language":"json","code":"{\n  status: \"400\",\n  message: \"An error occured\"\n}","name":""},{"status":200,"language":"json","code":"{\n  \"image\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/f/f0/Dynamixion_car_by_Buckminster_Fuller_1933_%28side_views%29.jpg/400px-Dynamixion_car_by_Buckminster_Fuller_1933_%28side_views%29.jpg\",\n  \"title\": \"Dymaxion car\",\n  \"start_production\": 1933,\n  \"class\": [\n    \"Concept car\"\n  ]\n}"}]},"settings":"","url":"/items/:collection/:id","auth":"required","examples":{"codes":[{"name":"node.js","language":"javascript","code":"client.getItem(id)\n.then(function(item) {\n  console.log(item);\n})\n\nclient.getItemByKeyValue('permalink', permalink)\n.then(function(item) {\n  console.log(item);\n})"}]},"method":"get"},"category":"5652f87a8cd6d43500158c99","githubsync":"","childrenPages":[]}

get/items/:collection/:id

get specific item

Definition

{{ api_url }}{{ page_api_url }}

Examples

Result Format



{"_id":"56532e92cd9a9717003b0696","api":{"settings":"","url":"/:collection/","auth":"required","examples":{"codes":[{"name":"node.js","language":"javascript","code":"var facets = {\n  tags:['drama', 'war']\n};\n\nclient.search({\n  sort: 'most_votes',\n  query: '',\n  page: 1,\n  aggs: JSON.stringify(facets),\n  per_page: 12\n}).then(function(res) {\n  console.log((res));\n})"}]},"method":"get","params":[{"in":"query","required":false,"desc":"","default":"1","type":"int","name":"page","_id":"56532e92cd9a9717003b069a","ref":""},{"required":false,"desc":"items count per page","default":"12","type":"int","name":"per_page","_id":"56532e92cd9a9717003b0699","ref":"","in":"query"},{"ref":"","in":"query","required":false,"desc":"search query string","default":"","type":"string","name":"query","_id":"56532e92cd9a9717003b0698"},{"in":"query","required":false,"desc":"i.e. \"brand:Audi OR brand:Mercedes\"","default":"","type":"string","name":"query_string","_id":"57a5e4a6e228650e008507b8","ref":""},{"required":false,"desc":"one of defined sort key","default":"","type":"string","name":"sort","_id":"56532e92cd9a9717003b0697","ref":"","in":"query"},{"ref":"","in":"query","required":false,"desc":"fields comma separated","default":"","type":"string","name":"fields","_id":"56533312b5083f2b0032487e"},{"default":"","type":"string","name":"aggs","_id":"5721f2c8ecb38d0e00d80eb5","ref":"","in":"query","required":false,"desc":"i.e. {brand: ['mercedes', 'audi'], condition: ['used']} (encoded string)"},{"in":"query","required":false,"desc":"field name","default":"","type":"string","name":"key","_id":"5721f2c8ecb38d0e00d80eb4","ref":""},{"required":false,"desc":"value for specific key name (working with key)","default":"","type":"string","name":"val","_id":"5721f2c8ecb38d0e00d80eb3","ref":"","in":"query"},{"type":"string","name":"load_aggs","_id":"57ed7376da9c632b008e66df","ref":"","in":"query","required":false,"desc":"comma separated list of aggregations i.e. \"tags,cities\"","default":""}],"results":{"codes":[{"language":"json","code":"{\n  meta: {\n    query: \"\",\n    sort: \"default\",\n    search_time: 15\n  },\n  pagination: {\n    page: 1,\n    per_page: 12,\n    total: 3000\n  },\n  data: {\n    items: [\n      {\n        id: 1173,\n        score: 1,\n        text: \"Don't cry because it's over, smile because it happened.\",\n        image: \"https://d.gr-assets.com/authors/1193930952p2/61105.jpg\",\n        author: \"Dr. Seuss\",\n        book: \"\",\n        tags: [\n          \"attributed-no-source\",\n          \"cry\",\n          \"crying\",\n          \"experience\",\n          \"happiness\",\n          \"joy\",\n          \"life\",\n          \"optimism\",\n          \"sadness\",\n          \"smile\",\n          \"smiling\"\n        ],\n        likes: 147550\n      },\n      {\n        id: 66,\n        score: 1,\n        text: \"So many books, so little time.\",\n        image: \"https://d.gr-assets.com/authors/1315160559p2/22302.jpg\",\n        author: \"Frank Zappa\",\n        book: \"\",\n        tags: [\n          \"books\",\n          \"humor\"\n        ],\n        likes: 89430\n      }\n    ],\n    aggregations: {\n      tags_terms: {\n        doc_count: 3000,\n        doc_count_error_upper_bound: 20,\n        sum_other_doc_count: 5335,\n        buckets: [\n          {\n            key: \"love\",\n            doc_count: 332\n          },\n          {\n            key: \"humor\",\n            doc_count: 272\n          },\n          {\n            key: \"inspirational\",\n            doc_count: 262\n          }\n        ],\n        title: \"tags_terms\",\n        name: \"tags_terms\",\n        type: \"terms\"\n      },\n      authors_terms: {\n        doc_count: 3000,\n        doc_count_error_upper_bound: 13,\n        sum_other_doc_count: 2355,\n        buckets: [\n          {\n            key: \"Cassandra Clare\",\n            doc_count: 118\n          },\n          {\n            key: \"J.K. Rowling\",\n            doc_count: 94\n          },\n          {\n            key: \"John Green\",\n            doc_count: 94\n          },\n          {\n            key: \"Oscar Wilde\",\n            doc_count: 63\n          }\n        ],\n        title: \"authors_terms\",\n        name: \"authors_terms\",\n        type: \"terms\"\n      }\n    },\n    sortings: { }\n  }\n}\n","name":"","status":200},{"code":"{}","name":"","status":400,"language":"json"}]}},"excerpt":"search items","githubsync":"","order":1,"sync_unique":"","body":"","hidden":false,"title":"/items/:collection","updates":[],"parentDoc":null,"version":"5652d740a3de712b00d176db","__v":5,"category":"5652f87a8cd6d43500158c99","createdAt":"2015-11-23T15:19:46.997Z","editedParams2":true,"isReference":true,"type":"get","user":"5652d72cfab156210023d20a","editedParams":true,"link_external":false,"link_url":"","project":"5652d740a3de712b00d176d8","slug":"search-items","childrenPages":[]}

get/items/:collection

search items

Query Params

page:
integer1
per_page:
integer12
items count per page
query:
string
search query string
query_string:
string
i.e. "brand:Audi OR brand:Mercedes"
sort:
string
one of defined sort key
fields:
string
fields comma separated
aggs:
string
i.e. {brand: ['mercedes', 'audi'], condition: ['used']} (encoded string)
key:
string
field name
val:
string
value for specific key name (working with key)
load_aggs:
string
comma separated list of aggregations i.e. "tags,cities"

Definition

{{ api_url }}{{ page_api_url }}

Examples

Result Format



{"_id":"56532cfbdb59ac35000a23e1","hidden":false,"isReference":true,"order":2,"body":"","createdAt":"2015-11-23T15:12:59.679Z","githubsync":"","type":"put","excerpt":"update item","category":"5652f87a8cd6d43500158c99","user":"5652d72cfab156210023d20a","link_external":false,"link_url":"","parentDoc":null,"project":"5652d740a3de712b00d176d8","slug":"update-item","sync_unique":"","__v":10,"api":{"settings":"","url":"/items/:collection/:id","auth":"required","examples":{"codes":[{"language":"json","code":"{\n  text: \"The secret to getting ahead is getting started.\",\n  author: \"Mark Twain\",\n  tags: [\n    \"starting\",\n    \"working\"\n  ]\n}","name":""}]},"method":"put","params":[],"results":{"codes":[{"language":"json","code":"{\n  status: \"success\"\n}","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]}},"version":"5652d740a3de712b00d176db","title":"/items/:collection/:id","updates":[],"childrenPages":[]}

put/items/:collection/:id

update item

Definition

{{ api_url }}{{ page_api_url }}

Examples

Result Format



{"_id":"565330c553aa2c170014212f","category":"5652f87a8cd6d43500158c99","parentDoc":null,"user":"5652d72cfab156210023d20a","version":"5652d740a3de712b00d176db","__v":4,"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit.","createdAt":"2015-11-23T15:29:09.668Z","githubsync":"","isReference":true,"project":"5652d740a3de712b00d176d8","sync_unique":"","api":{"auth":"required","examples":{"codes":[]},"method":"delete","params":[],"results":{"codes":[{"name":"","status":200,"language":"json","code":"{\n}"},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","url":"/:id"},"hidden":false,"link_external":false,"order":3,"slug":"delete-item","excerpt":"delete specific item","link_url":"","title":"/items/:collection/:id","type":"delete","updates":[],"childrenPages":[]}

delete/items/:collection/:id

delete specific item
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Definition

{{ api_url }}{{ page_api_url }}

Result Format



Lorem ipsum dolor sit amet, consectetur adipiscing elit.
{"_id":"5653326bb7e25e2100d0120a","createdAt":"2015-11-23T15:36:11.256Z","excerpt":"add new item","hidden":false,"__v":5,"api":{"url":"/:collection","auth":"required","examples":{"codes":[{"code":"{\n  text: \"The secret to getting ahead is getting started.\",\n  author: \"Mark Twain\",\n  tags: [\n    \"starting\",\n    \"working\"\n  ]\n}","name":"","language":"json"}]},"method":"post","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{ \n  id: '100', \n  collection: 'movie', \n  project: 'project' \n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":""},"category":"5652f87a8cd6d43500158c99","project":"5652d740a3de712b00d176d8","title":"/items/:collection","type":"post","body":"","githubsync":"","isReference":true,"order":4,"slug":"create-item","updates":[],"link_external":false,"link_url":"","version":"5652d740a3de712b00d176db","parentDoc":null,"sync_unique":"","user":"5652d72cfab156210023d20a","childrenPages":[]}

post/items/:collection

add new item

Definition

{{ api_url }}{{ page_api_url }}

Examples

Result Format



{"_id":"5721f01149df4f0e00528360","__v":1,"api":{"auth":"required","examples":{"codes":[{"code":"var ItemsAPI = require('itemsapi-node');\nvar client = new ItemsAPI('http://localhost:5000/api/v1', 'movie');\n\nclient.similar(id, {\n  fields: fields\n})\n.then(function(items) {\n  console.log(items);\n})\n","language":"javascript","name":"node.js"}]},"method":"get","params":[{"_id":"5721f01149df4f0e00528361","ref":"","in":"query","required":false,"desc":"fields for calculating similarity (comma delimiter) i.e. tags","default":"","type":"string","name":"fields"},{"name":"query_string","_id":"57aded6b3f00b90e00b7c981","ref":"","in":"query","required":false,"desc":"i.e. \"enabled:true OR missing:enabled\"","default":"","type":"string"}],"results":{"codes":[{"status":200,"language":"json","code":"\n  \"meta\": {\n    \n  },\n  \"pagination\": {\n    \"per_page\": 8,\n    \"total\": 528\n  },\n  \"data\": {\n    \"items\": [\n      {\n        \"id\": \"AVXfAOj8MT8dFYnmUne7\",\n        \"score\": 1.4048446,\n        \"image\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/f/f0/Vintage_car_at_the_Wirral_Bus_%26_Tram_Show_-_DSC03336.JPG/400px-Vintage_car_at_the_Wirral_Bus_%26_Tram_Show_-_DSC03336.JPG\",\n        \"title\": \"Vauxhall Chevette\",\n        \"start_production\": 1975,\n        \"class\": [\n          \"Supermini\"\n        ]\n      },\n      {\n        \"id\": \"AVXfAOj8MT8dFYnmUne9\",\n        \"score\": 1.3857335,\n        \"image\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/f/f0/Ford_Crown_Victoria_LX.jpg/400px-Ford_Crown_Victoria_LX.jpg\",\n        \"title\": \"Ford Crown Victoria\",\n        \"start_production\": 1955,\n        \"class\": [\n          \"Full-size Ford\"\n        ]\n      },\n      {\n        \"id\": \"AVXfAOj9MT8dFYnmUniL\",\n        \"score\": 1.3857335,\n        \"image\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/f/f0/66Sat.jpg/400px-66Sat.jpg\",\n        \"title\": \"Plymouth Satellite\",\n        \"start_production\": 1964,\n        \"class\": [\n          \"Mid-size\"\n        ]\n      },\n      {\n        \"id\": \"AVXfAOj_MT8dFYnmUnmv\",\n        \"score\": 1.0664734,\n        \"image\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/f/fd/Kings_Ferry_6.21_FJ61EXF_%288717059549%29.jpg/400px-Kings_Ferry_6.21_FJ61EXF_%288717059549%29.jpg\",\n        \"title\": \"Volvo B13R\",\n        \"start_production\": 2009,\n        \"class\": [\n          \"Coach chassis\"\n        ]\n      },\n      {\n        \"id\": \"AVXfAOj_MT8dFYnmUnld\",\n        \"score\": 1.0604744,\n        \"image\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/f/fa/1974_Chevrolet_%2810754212153%29.jpg/400px-1974_Chevrolet_%2810754212153%29.jpg\",\n        \"title\": \"Chevrolet Impala (fifth generation)\",\n        \"start_production\": 1970\n      },\n      {\n        \"id\": \"AVXfAOj_MT8dFYnmUnmz\",\n        \"score\": 1.0604744,\n        \"image\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/f/f8/2014_Ford_Tourneo_Courier_%28fl%29.jpg/400px-2014_Ford_Tourneo_Courier_%28fl%29.jpg\",\n        \"title\": \"Ford Transit Courier\",\n        \"start_production\": 2014,\n        \"class\": [\n          \"Leisure activity vehicle\"\n        ]\n      },\n      {\n        \"id\": \"AVXfAOj9MT8dFYnmUnhL\",\n        \"score\": 0.97680193,\n        \"image\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/f/fa/%2786_Shelby_GLHS_%28Orange_Julep_%2709%29.jpg/400px-%2786_Shelby_GLHS_%28Orange_Julep_%2709%29.jpg\",\n        \"title\": \"Shelby GLHS\",\n        \"start_production\": 1986,\n        \"class\": [\n          \"Sport compact\"\n        ]\n      },\n      {\n        \"id\": \"AVXfAOj8MT8dFYnmUnfo\",\n        \"score\": 0.90181595,\n        \"image\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/5/5a/2015_Audi_A4_B9_3.0_TDI_quattro_V6_200_kW_S_line_Tangorot_Vorderansicht_%28cropped%29.jpg/400px-2015_Audi_A4_B9_3.0_TDI_quattro_V6_200_kW_S_line_Tangorot_Vorderansicht_%28cropped%29.jpg\",\n        \"title\": \"Audi A4\",\n        \"class\": [\n          \"Compact executive car\"\n        ]\n      },\n      {\n        \"id\": \"AVXfAOj9MT8dFYnmUniJ\",\n        \"score\": 0.90181595,\n        \"image\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/8/8c/Bentley_S1_%28Byward_Auto_Classic%29.jpg/400px-Bentley_S1_%28Byward_Auto_Classic%29.jpg\",\n        \"title\": \"Bentley S1\",\n        \"start_production\": 1955,\n        \"class\": [\n          \"Full-size luxury car\"\n        ]\n      },\n      {\n        \"id\": \"AVXfAOj9MT8dFYnmUniw\",\n        \"score\": 0.90181595,\n        \"image\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/0/06/2007_Toyota_Aurion_Prodigy_06_%28edit_5%29.jpg/400px-2007_Toyota_Aurion_Prodigy_06_%28edit_5%29.jpg\",\n        \"title\": \"Toyota Aurion (XV40)\",\n        \"start_production\": 2006,\n        \"class\": [\n          \"Mid-size car\"\n        ]\n      }\n    ]\n  }\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/items/:collection/:id/similar"},"createdAt":"2016-04-28T11:12:17.041Z","editedParams":true,"sync_unique":"","updates":[],"body":"Looks like:\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/41h0SjCSbWBP7Vw96xTF_Selection_250.jpg\",\n        \"Selection_250.jpg\",\n        \"760\",\n        \"485\",\n        \"#7c624f\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nMore technical of how it is done here: https://www.elastic.co/guide/en/elasticsearch/reference/1.6/query-dsl-mlt-query.html","type":"get","user":"5652d72cfab156210023d20a","hidden":false,"link_external":false,"parentDoc":null,"project":"5652d740a3de712b00d176d8","title":"/items/:collection/:id/similar","slug":"itemscollectionidsimilar","category":"5652f87a8cd6d43500158c99","editedParams2":true,"excerpt":"It provides similar items based on collaborative filtering algorithm","githubsync":"","isReference":true,"link_url":"","order":5,"version":"5652d740a3de712b00d176db","childrenPages":[]}

get/items/:collection/:id/similar

It provides similar items based on collaborative filtering algorithm

Query Params

fields:
string
fields for calculating similarity (comma delimiter) i.e. tags
query_string:
string
i.e. "enabled:true OR missing:enabled"
Looks like: [block:image] { "images": [ { "image": [ "https://files.readme.io/41h0SjCSbWBP7Vw96xTF_Selection_250.jpg", "Selection_250.jpg", "760", "485", "#7c624f", "" ] } ] } [/block] More technical of how it is done here: https://www.elastic.co/guide/en/elasticsearch/reference/1.6/query-dsl-mlt-query.html

Definition

{{ api_url }}{{ page_api_url }}

Examples

Result Format



Looks like: [block:image] { "images": [ { "image": [ "https://files.readme.io/41h0SjCSbWBP7Vw96xTF_Selection_250.jpg", "Selection_250.jpg", "760", "485", "#7c624f", "" ] } ] } [/block] More technical of how it is done here: https://www.elastic.co/guide/en/elasticsearch/reference/1.6/query-dsl-mlt-query.html
{"_id":"5739ab621f4b740e00b06db3","api":{"examples":{"codes":[]},"method":"put","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"","auth":"required"},"githubsync":"","link_url":"","version":"5652d740a3de712b00d176db","type":"put","updates":[],"body":"Enable item - enabled items will be visible in search\ni.e. `/items/movies?enabled=true` or `/items/movies?enabled=false`\n\nYou can disable item by `PUT` `/items/:collection/:id/disable`","category":"5652f87a8cd6d43500158c99","excerpt":"","link_external":false,"sync_unique":"","title":"/items/:collection/:id/enable","user":"5652d72cfab156210023d20a","hidden":false,"isReference":true,"slug":"itemscollectionidenable","__v":2,"createdAt":"2016-05-16T11:13:38.551Z","order":999,"project":"5652d740a3de712b00d176d8","childrenPages":[]}

put/items/:collection/:id/enable

Enable item - enabled items will be visible in search i.e. `/items/movies?enabled=true` or `/items/movies?enabled=false` You can disable item by `PUT` `/items/:collection/:id/disable`
Enable item - enabled items will be visible in search i.e. `/items/movies?enabled=true` or `/items/movies?enabled=false` You can disable item by `PUT` `/items/:collection/:id/disable`
{"_id":"57867cd0e5cdf20e007d384a","editedParams2":true,"excerpt":"","githubsync":"","slug":"aggregationscollectionaggregation_name","sync_unique":"","title":"/aggregations/:collection/:aggregation_name","version":"5652d740a3de712b00d176db","body":"You can use aggregations as always while searching:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/P3hjRdkVQUqhXpZqbwzW_89634d9c-4844-11e6-8ad1-237dae0e423c.png\",\n        \"89634d9c-4844-11e6-8ad1-237dae0e423c.png\",\n        \"410\",\n        \"373\",\n        \"#6495c0\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nAnd show all results on another page:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/vM6HvSR2Tum8MHiROtHx_90f8bfb0-4844-11e6-8938-8fcd0e9d37b1.png\",\n        \"90f8bfb0-4844-11e6-8938-8fcd0e9d37b1.png\",\n        \"1126\",\n        \"649\",\n        \"#267ccb\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nLet's assume you have collection `cities`\n\n```json\n{\n    \"name\": \"cities\",\n    \"schema\": {\n        \"country\": {\n            \"type\": \"string\",\n            \"index\": \"not_analyzed\",\n            \"store\": true\n        }\n    },\n    \"aggregations\": {\n        \"country\": {\n            \"type\": \"terms\",\n            \"field\": \"country\",\n            \"size\": 10,\n            \"title\": \"Country\"\n        }\n    }\n}\n```\n\nTo show sorted, paginated results:\n`GET /api/v1/aggregations/cities/country?page=1&per_page=10&size=100&sort=_term&order=asc`\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Currently working on caching for that feature. It can be useful for bigger data because elasticsearch load all aggregation data into memory. More info soon!\"\n}\n[/block]\nDiscussion about that feature: https://github.com/itemsapi/itemsapi/issues/131","project":"5652d740a3de712b00d176d8","user":"5652d72cfab156210023d20a","hidden":false,"api":{"auth":"required","examples":{"codes":[]},"method":"get","params":[{"ref":"","in":"query","required":false,"desc":"","default":"1","type":"int","name":"page","_id":"57867ea3b2f4060e00fa3a04"},{"in":"query","required":false,"desc":"","default":"10","type":"int","name":"per_page","_id":"57867ea3b2f4060e00fa3a03","ref":""},{"desc":"how much elements from elasticsearch load into memory","default":"100","type":"int","name":"size","_id":"57867ea3b2f4060e00fa3a02","ref":"","in":"query","required":false},{"name":"sort","_id":"57867ea3b2f4060e00fa3a01","ref":"","in":"query","required":false,"desc":"_count or  _term","default":"_count","type":"string"},{"ref":"","in":"query","required":false,"desc":"desc or asc","default":"desc","type":"string","name":"order","_id":"57867ea3b2f4060e00fa3a00"},{"default":"","type":"string","name":"aggs","_id":"578751a3021efa0e00ebb7fa","ref":"","in":"query","required":false,"desc":"i.e. {brand: ['Mercedes', 'Audi']} (encoded string)"},{"in":"query","required":false,"desc":"search through items","default":"","type":"string","name":"query","_id":"578751a3021efa0e00ebb7f9","ref":""},{"desc":"search through aggregation results","default":"","type":"string","name":"aggregation_query","_id":"5787632baff9b81900afc686","ref":"","in":"query","required":false},{"name":"query_string","_id":"57a72686eb14b60e00e37d6a","ref":"","in":"query","required":false,"desc":"i.e. \"enabled:true OR _missing_:enabled\"","default":"","type":"string"}],"results":{"codes":[{"code":"{\n  \"data\": {\n    \"buckets\": [\n      {\n        \"key\": \"Compact\",\n        \"doc_count\": 21,\n        \"permalink\": \"compact\"\n      },\n      {\n        \"key\": \"Compact car\",\n        \"doc_count\": 21,\n        \"permalink\": \"compact-car\"\n      }\n    ]\n  },\n  \"pagination\": {\n    \"page\": 2,\n    \"per_page\": 2,\n    \"total\": 536\n  },\n  \"meta\": {\n    \"title\": \"class\",\n    \"name\": \"class\",\n    \"type\": \"terms\"\n  }\n}","status":200,"language":"json"}]},"settings":"","url":"/aggregations/:collection/:aggregation_name"},"category":"57867c9ab2f4060e00fa39fc","createdAt":"2016-07-13T17:39:28.554Z","link_url":"","type":"get","__v":4,"isReference":true,"link_external":false,"order":999,"updates":[],"editedParams":true,"childrenPages":[]}

get/aggregations/:collection/:aggregation_name

Query Params

page:
integer1
per_page:
integer10
size:
integer100
how much elements from elasticsearch load into memory
sort:
string_count
_count or _term
order:
stringdesc
desc or asc
aggs:
string
i.e. {brand: ['Mercedes', 'Audi']} (encoded string)
query:
string
search through items
aggregation_query:
string
search through aggregation results
query_string:
string
i.e. "enabled:true OR _missing_:enabled"
You can use aggregations as always while searching: [block:image] { "images": [ { "image": [ "https://files.readme.io/P3hjRdkVQUqhXpZqbwzW_89634d9c-4844-11e6-8ad1-237dae0e423c.png", "89634d9c-4844-11e6-8ad1-237dae0e423c.png", "410", "373", "#6495c0", "" ] } ] } [/block] And show all results on another page: [block:image] { "images": [ { "image": [ "https://files.readme.io/vM6HvSR2Tum8MHiROtHx_90f8bfb0-4844-11e6-8938-8fcd0e9d37b1.png", "90f8bfb0-4844-11e6-8938-8fcd0e9d37b1.png", "1126", "649", "#267ccb", "" ] } ] } [/block] Let's assume you have collection `cities` ```json { "name": "cities", "schema": { "country": { "type": "string", "index": "not_analyzed", "store": true } }, "aggregations": { "country": { "type": "terms", "field": "country", "size": 10, "title": "Country" } } } ``` To show sorted, paginated results: `GET /api/v1/aggregations/cities/country?page=1&per_page=10&size=100&sort=_term&order=asc` [block:callout] { "type": "info", "body": "Currently working on caching for that feature. It can be useful for bigger data because elasticsearch load all aggregation data into memory. More info soon!" } [/block] Discussion about that feature: https://github.com/itemsapi/itemsapi/issues/131

Definition

{{ api_url }}{{ page_api_url }}

Result Format



You can use aggregations as always while searching: [block:image] { "images": [ { "image": [ "https://files.readme.io/P3hjRdkVQUqhXpZqbwzW_89634d9c-4844-11e6-8ad1-237dae0e423c.png", "89634d9c-4844-11e6-8ad1-237dae0e423c.png", "410", "373", "#6495c0", "" ] } ] } [/block] And show all results on another page: [block:image] { "images": [ { "image": [ "https://files.readme.io/vM6HvSR2Tum8MHiROtHx_90f8bfb0-4844-11e6-8938-8fcd0e9d37b1.png", "90f8bfb0-4844-11e6-8938-8fcd0e9d37b1.png", "1126", "649", "#267ccb", "" ] } ] } [/block] Let's assume you have collection `cities` ```json { "name": "cities", "schema": { "country": { "type": "string", "index": "not_analyzed", "store": true } }, "aggregations": { "country": { "type": "terms", "field": "country", "size": 10, "title": "Country" } } } ``` To show sorted, paginated results: `GET /api/v1/aggregations/cities/country?page=1&per_page=10&size=100&sort=_term&order=asc` [block:callout] { "type": "info", "body": "Currently working on caching for that feature. It can be useful for bigger data because elasticsearch load all aggregation data into memory. More info soon!" } [/block] Discussion about that feature: https://github.com/itemsapi/itemsapi/issues/131
{"_id":"57e438c3f727c417000020ef","__v":0,"createdAt":"2016-09-22T20:02:11.491Z","githubsync":"","link_url":"","slug":"aggregationscollectionfieldfield_name","title":"/aggregations/:collection/field/:field_name","type":"get","updates":[],"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The API and query params are almost identical as in the endpoint above. It only differs by endpoint. The above is aggregating by aggregation name specified in configuration and this one is aggregated directly by field from schema\",\n  \"title\": \"Difference with above endpoint\"\n}\n[/block]","isReference":true,"link_external":false,"order":999,"project":"5652d740a3de712b00d176d8","version":"5652d740a3de712b00d176db","category":"57867c9ab2f4060e00fa39fc","excerpt":"","hidden":false,"api":{"url":"/aggregations/:collection/field/:field_name","auth":"required","examples":{"codes":[]},"method":"get","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"data\": {\n    \"buckets\": [\n      {\n        \"key\": \"Compact\",\n        \"doc_count\": 21,\n        \"permalink\": \"compact\"\n      },\n      {\n        \"key\": \"Compact car\",\n        \"doc_count\": 21,\n        \"permalink\": \"compact-car\"\n      }\n    ]\n  },\n  \"pagination\": {\n    \"page\": 2,\n    \"per_page\": 2,\n    \"total\": 536\n  },\n  \"meta\": {\n    \"title\": \"class\",\n    \"name\": \"class\",\n    \"type\": \"terms\"\n  }\n}"}]},"settings":""},"sync_unique":"","user":"5652d72cfab156210023d20a","childrenPages":[]}

get/aggregations/:collection/field/:field_name

[block:callout] { "type": "warning", "body": "The API and query params are almost identical as in the endpoint above. It only differs by endpoint. The above is aggregating by aggregation name specified in configuration and this one is aggregated directly by field from schema", "title": "Difference with above endpoint" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Result Format



[block:callout] { "type": "warning", "body": "The API and query params are almost identical as in the endpoint above. It only differs by endpoint. The above is aggregating by aggregation name specified in configuration and this one is aggregated directly by field from schema", "title": "Difference with above endpoint" } [/block]
{"_id":"5653747d5e1c5d0d0043fb24","hidden":false,"isReference":true,"link_url":"","parentDoc":null,"project":"5652d740a3de712b00d176d8","sync_unique":"","createdAt":"2015-11-23T20:18:05.077Z","link_external":false,"updates":[],"version":"5652d740a3de712b00d176db","body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Showing count for each collection was probably a design mistake because it requires to make additional request for each collection. This endpoint should be as simple as possible with original values and pagination\\n\\nFor showing collections with count there should be additional custom endpoint. I don't want to make break changes right now though..\",\n  \"title\": \"count field\"\n}\n[/block]","excerpt":"return list of collections with statistics","githubsync":"","order":0,"title":"/collections","__v":3,"api":{"auth":"required","examples":{"codes":[]},"method":"get","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{\n  meta: { },\n  pagination: {\n    page: 1,\n    per_page: 10,\n    total: 2\n  },\n  data: {\n    items: [\n      {\n        name: \"movies\",\n        display_name: \"Movies\",\n        count: 8060\n      },\n      {\n        name: \"songs\",\n        display_name: \"Songs\",\n        count: 5068\n      }\n    ]\n  }\n}\n","name":""}]},"settings":"","url":"/collections"},"category":"56995471113a901900ef8f6f","slug":"collections","type":"get","user":"5652d72cfab156210023d20a","childrenPages":[]}

get/collections

return list of collections with statistics
[block:callout] { "type": "warning", "body": "Showing count for each collection was probably a design mistake because it requires to make additional request for each collection. This endpoint should be as simple as possible with original values and pagination\n\nFor showing collections with count there should be additional custom endpoint. I don't want to make break changes right now though..", "title": "count field" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Result Format



[block:callout] { "type": "warning", "body": "Showing count for each collection was probably a design mistake because it requires to make additional request for each collection. This endpoint should be as simple as possible with original values and pagination\n\nFor showing collections with count there should be additional custom endpoint. I don't want to make break changes right now though..", "title": "count field" } [/block]
{"_id":"56995542cb127f0d003cc160","link_url":"","project":"5652d740a3de712b00d176d8","type":"post","updates":[],"api":{"method":"post","params":[],"results":{"codes":[{"status":200,"language":"json","code":"","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/collections","auth":"required","examples":{"codes":[{"language":"json","code":"{\n  \"name\": \"movies\",\n  \"project\": \"Project1\",\n  \"schema\": {},\n  \"aggregations\": {},\n  \"sortings\": {}\n}","name":""}]}},"excerpt":"add new item","link_external":false,"parentDoc":null,"slug":"collections-1","sync_unique":"","user":"5652d72cfab156210023d20a","__v":0,"isReference":true,"hidden":false,"order":1,"title":"/collections","version":"5652d740a3de712b00d176db","body":"","githubsync":"","createdAt":"2016-01-15T20:23:30.056Z","category":"56995471113a901900ef8f6f","childrenPages":[]}

post/collections

add new item

Definition

{{ api_url }}{{ page_api_url }}

Examples



{"_id":"5699557394a308190081fe75","sync_unique":"","title":"/collections/:id","user":"5652d72cfab156210023d20a","body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit.","createdAt":"2016-01-15T20:24:19.602Z","link_url":"","parentDoc":null,"githubsync":"","hidden":false,"type":"delete","__v":0,"api":{"auth":"required","examples":{"codes":[]},"method":"delete","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/collections/:id"},"excerpt":"delete specific collection","version":"5652d740a3de712b00d176db","category":"56995471113a901900ef8f6f","isReference":true,"order":2,"updates":[],"link_external":false,"project":"5652d740a3de712b00d176d8","slug":"collectionsid","childrenPages":[]}

delete/collections/:id

delete specific collection
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Definition

{{ api_url }}{{ page_api_url }}

Result Format



Lorem ipsum dolor sit amet, consectetur adipiscing elit.
{"_id":"5699561554d7db17000ee9dc","githubsync":"","link_url":"","sync_unique":"","user":"5652d72cfab156210023d20a","version":"5652d740a3de712b00d176db","category":"56995471113a901900ef8f6f","excerpt":"get specific collection","hidden":false,"isReference":true,"link_external":false,"parentDoc":null,"slug":"collectionsname-1","__v":2,"body":"","createdAt":"2016-01-15T20:27:01.239Z","title":"/collections/:name","order":3,"project":"5652d740a3de712b00d176d8","api":{"auth":"required","examples":{"codes":[]},"method":"get","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"name\": \"cars\",\n  \"schema\": {\n    \"image\": {\n      \"type\": \"string\",\n      \"display\": \"image\"\n    },\n    \"title\": {\n      \"type\": \"string\",\n      \"store\": true\n    },\n    \"start_production\": {\n      \"type\": \"integer\",\n      \"store\": true\n    },\n    \"class\": {\n      \"type\": \"string\",\n      \"display\": \"array\",\n      \"index\": \"not_analyzed\",\n      \"store\": true\n    }\n  },\n  \"aggregations\": {\n    \"start_production\": {\n      \"type\": \"range\",\n      \"field\": \"start_production\",\n      \"title\": \"start_production\",\n      \"ranges\": [\n        {\n          \"name\": \"1929 - 1946\",\n          \"lte\": 1946\n        },\n        {\n          \"name\": \"1946 - 1963\",\n          \"lte\": 1963,\n          \"gte\": 1946\n        },\n        {\n          \"name\": \"1963 - 1980\",\n          \"lte\": 1980,\n          \"gte\": 1963\n        },\n        {\n          \"name\": \"1980 - 1997\",\n          \"lte\": 1997,\n          \"gte\": 1980\n        },\n        {\n          \"name\": \"1997 - 2016\",\n          \"gte\": 1997\n        }\n      ]\n    },\n    \"class\": {\n      \"type\": \"terms\",\n      \"size\": 10,\n      \"sort\": \"_count\",\n      \"order\": \"desc\",\n      \"field\": \"class\",\n      \"title\": \"class\"\n    }\n  },\n  \"sortings\": {\n    \"title\": {\n      \"title\": \"title\",\n      \"type\": \"normal\",\n      \"order\": \"desc\",\n      \"field\": \"title\"\n    },\n    \"start_production\": {\n      \"title\": \"start_production\",\n      \"type\": \"normal\",\n      \"order\": \"desc\",\n      \"field\": \"start_production\"\n    }\n  },\n  \"created_at\": \"2016-07-12T12:07:06.574Z\",\n  \"updated_at\": \"2016-07-12T12:07:06.574Z\"\n}","name":""},{"code":"{\n  status: \"400\",\n  message: \"An error occured\"\n}","name":"","status":400,"language":"json"}]},"settings":"","url":"/collections/:name"},"type":"get","updates":[],"childrenPages":[]}

get/collections/:name

get specific collection

Definition

{{ api_url }}{{ page_api_url }}

Result Format



{"_id":"569955d57465970d00650bae","category":"56995471113a901900ef8f6f","isReference":true,"link_external":false,"user":"5652d72cfab156210023d20a","__v":0,"api":{"settings":"","url":"/collections/:name","auth":"required","examples":{"codes":[{"language":"json","code":"{\n  \"schema\": {},\n  \"aggregations\": {},\n  \"sortings\": {}\n}","name":""}]},"method":"put","params":[],"results":{"codes":[{"name":"","status":200,"language":"json","code":""},{"status":400,"language":"json","code":"{}","name":""}]}},"body":"","link_url":"","slug":"collectionsname","title":"/collections/:name","excerpt":"edit collection","project":"5652d740a3de712b00d176d8","updates":[],"version":"5652d740a3de712b00d176db","createdAt":"2016-01-15T20:25:57.382Z","githubsync":"","hidden":false,"order":4,"parentDoc":null,"sync_unique":"","type":"put","childrenPages":[]}

put/collections/:name

edit collection

Definition

{{ api_url }}{{ page_api_url }}

Examples



{"_id":"574f436681a71120005fb4fb","slug":"collectionsgenerate","editedParams2":true,"excerpt":"Generate collections for provided data","hidden":false,"githubsync":"","link_external":false,"sync_unique":"","user":"5652d72cfab156210023d20a","version":"5652d740a3de712b00d176db","__v":0,"api":{"settings":"","url":"/collections/generate","auth":"required","examples":{"codes":[]},"method":"put","params":[{"desc":"items (json)","default":"","type":"array_object","name":"body","in":"body","_id":"574f436681a71120005fb4fd","ref":"","required":false},{"name":"name","in":"body","_id":"574f436681a71120005fb4fc","ref":"","required":false,"desc":"name of collection","default":"","type":"string"}],"results":{"codes":[{"language":"text","code":""}]}},"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"It is for read-only purposes. Collection is not persisted to the local db.. \\nIf you provide params properly then you get auto generated suggested configuration by the system\"\n}\n[/block]","title":"/collections/generate","type":"put","updates":[],"editedParams":true,"link_url":"","order":999,"isReference":true,"project":"5652d740a3de712b00d176d8","category":"56995471113a901900ef8f6f","createdAt":"2016-06-01T20:19:50.393Z","childrenPages":[]}

put/collections/generate

Generate collections for provided data

Body Params

body:
array of objects
items (json)
name:
string
name of collection
[block:callout] { "type": "info", "body": "It is for read-only purposes. Collection is not persisted to the local db.. \nIf you provide params properly then you get auto generated suggested configuration by the system" } [/block]

Definition

{{ api_url }}{{ page_api_url }}


[block:callout] { "type": "info", "body": "It is for read-only purposes. Collection is not persisted to the local db.. \nIf you provide params properly then you get auto generated suggested configuration by the system" } [/block]
{"_id":"569a14750213820d00ac4b2f","__v":3,"api":{"examples":{"codes":[]},"method":"get","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"cars_index\": {\n    \"mappings\": {\n      \"cars\": {\n        \"properties\": {\n          \"class\": {\n            \"type\": \"string\",\n            \"index\": \"not_analyzed\",\n            \"store\": true\n          },\n          \"image\": {\n            \"type\": \"string\"\n          },\n          \"start_production\": {\n            \"type\": \"integer\",\n            \"store\": true\n          },\n          \"title\": {\n            \"type\": \"string\",\n            \"store\": true\n          }\n        }\n      }\n    }\n  }\n}","name":""},{"status":400,"language":"json","code":"{\n  status: \"400\",\n  message: \"An error occured\"\n}","name":""}]},"settings":"","url":"/collections/:name/mapping","auth":"required"},"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"It gets original elasticsearch mapping\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Not sure why it returns all mappings for index (example on the right side). In some of the next version it should return one specific mapping for collection name\"\n}\n[/block]","githubsync":"","link_external":false,"updates":[],"category":"569a14d16666490d005ac29f","createdAt":"2016-01-16T09:59:17.040Z","project":"5652d740a3de712b00d176d8","excerpt":"get collection ES mapping","hidden":false,"order":0,"parentDoc":null,"slug":"collectionsnamemapping-1","isReference":true,"link_url":"","sync_unique":"","title":"/collections/:name/mapping","type":"get","user":"5652d72cfab156210023d20a","version":"5652d740a3de712b00d176db","childrenPages":[]}

get/collections/:name/mapping

get collection ES mapping
[block:callout] { "type": "info", "body": "It gets original elasticsearch mapping" } [/block] [block:callout] { "type": "warning", "body": "Not sure why it returns all mappings for index (example on the right side). In some of the next version it should return one specific mapping for collection name" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Result Format



[block:callout] { "type": "info", "body": "It gets original elasticsearch mapping" } [/block] [block:callout] { "type": "warning", "body": "Not sure why it returns all mappings for index (example on the right side). In some of the next version it should return one specific mapping for collection name" } [/block]
{"_id":"569a145e80d43a0d00304f9d","body":"","excerpt":"update collection mapping in elasticsearch","isReference":true,"link_external":false,"updates":[],"version":"5652d740a3de712b00d176db","api":{"auth":"required","examples":{"codes":[{"code":"","name":"","language":"json"}]},"method":"put","params":[],"results":{"codes":[{"status":200,"language":"json","code":"","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/collections/:name/mapping"},"githubsync":"","link_url":"","title":"/collections/:name/mapping","user":"5652d72cfab156210023d20a","__v":0,"createdAt":"2016-01-16T09:58:54.844Z","parentDoc":null,"project":"5652d740a3de712b00d176d8","slug":"collectionsnamemapping","sync_unique":"","type":"put","category":"569a14d16666490d005ac29f","hidden":false,"order":1,"childrenPages":[]}

put/collections/:name/mapping

update collection mapping in elasticsearch

Definition

{{ api_url }}{{ page_api_url }}


{"_id":"569a14bf0213820d00ac4b31","link_external":false,"sync_unique":"","title":"/collections/:name/mapping","__v":0,"api":{"method":"post","params":[],"results":{"codes":[{"status":200,"language":"json","code":"","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":"/collections/:name/mapping","auth":"required","examples":{"codes":[{"language":"json","code":"","name":""}]}},"createdAt":"2016-01-16T10:00:31.992Z","isReference":true,"type":"post","updates":[],"user":"5652d72cfab156210023d20a","version":"5652d740a3de712b00d176db","githubsync":"","link_url":"","order":2,"slug":"collectionsnamemapping-2","body":"It creates mapping in elasticsearch and get schema from collection. If index doesn't exists in ES it creates it as well","hidden":false,"parentDoc":null,"category":"569a14d16666490d005ac29f","excerpt":"add new item","project":"5652d740a3de712b00d176d8","childrenPages":[]}

post/collections/:name/mapping

add new item
It creates mapping in elasticsearch and get schema from collection. If index doesn't exists in ES it creates it as well

Definition

{{ api_url }}{{ page_api_url }}


It creates mapping in elasticsearch and get schema from collection. If index doesn't exists in ES it creates it as well
{"_id":"5653359f9238a81700527caa","category":"56533535b5083f2b00324885","createdAt":"2015-11-23T15:49:51.339Z","link_external":false,"sync_unique":"","__v":1,"isReference":false,"order":0,"parentDoc":null,"slug":"contribution","user":"5652d72cfab156210023d20a","excerpt":"","githubsync":"","updates":[],"version":"5652d740a3de712b00d176db","hidden":false,"project":"5652d740a3de712b00d176d8","link_url":"","title":"Contribution","type":"basic","api":{"url":"","auth":"required","params":[],"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"settings":""},"body":"Clone the repository to your host and install dependencies.\n\n```\n$ git clone https://github.com/itemsapi/item.git\n$ cd item\n$ npm install\n```\n\nCreate a feature branch.\n```\n$ git checkout -b new_feature\n```\nStart hacking. Push the branch:\n\n```\n$ git push origin new_feature\nCreate a pull request and describe the change.\n```","childrenPages":[]}

Contribution

Clone the repository to your host and install dependencies. ``` $ git clone https://github.com/itemsapi/item.git $ cd item $ npm install ``` Create a feature branch. ``` $ git checkout -b new_feature ``` Start hacking. Push the branch: ``` $ git push origin new_feature Create a pull request and describe the change. ```
Clone the repository to your host and install dependencies. ``` $ git clone https://github.com/itemsapi/item.git $ cd item $ npm install ``` Create a feature branch. ``` $ git checkout -b new_feature ``` Start hacking. Push the branch: ``` $ git push origin new_feature Create a pull request and describe the change. ```
{"_id":"574f402b2218bf0e00cf8ffb","category":"574f3fd3014ddc0e00d14846","editedParams":true,"order":999,"sync_unique":"","updates":[],"isReference":true,"link_url":"","type":"post","api":{"examples":{"codes":[]},"method":"post","params":[{"default":"","type":"string","name":"name","in":"body","_id":"574f41e525b18b2400a2c314","ref":"","required":false,"desc":"name of collection"},{"in":"body","_id":"574f40e81866ba2000108397","ref":"","required":false,"desc":"whether collection configuration should be generated automatically","default":"","type":"string","name":"auto"},{"name":"collection","in":"body","_id":"574f40e81866ba2000108396","ref":"","required":false,"desc":"collection configuration","default":"","type":"object"},{"desc":"url to json data (items)","default":"","type":"string","name":"url","in":"body","_id":"574f40e81866ba2000108395","ref":"","required":false},{"name":"data","in":"body","_id":"574f40e81866ba2000108394","ref":"","required":false,"desc":"json data (items)","default":"","type":"array_object"}],"results":{"codes":[{"name":"","code":"{\n  name: 'restaurants'\n}","language":"json","status":200},{"code":"{}","language":"json","status":400,"name":""}]},"settings":"","url":"/projects","auth":"required"},"githubsync":"","hidden":false,"link_external":false,"version":"5652d740a3de712b00d176db","editedParams2":true,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Almost all parameters are optional\\nIf you don't provide name it will be random name\\nIf you don't provide collection it will be auto configured by items\\n\\nurl or data should be provided\"\n}\n[/block]","createdAt":"2016-06-01T20:06:03.722Z","excerpt":"It creates new project (collection + mapping + items) in one request","project":"5652d740a3de712b00d176d8","slug":"projects","title":"/projects","user":"5652d72cfab156210023d20a","__v":2,"childrenPages":[]}

post/projects

It creates new project (collection + mapping + items) in one request

Body Params

name:
string
name of collection
auto:
string
whether collection configuration should be generated automatically
collection:
object
collection configuration
url:
string
url to json data (items)
data:
array of objects
json data (items)
[block:callout] { "type": "info", "body": "Almost all parameters are optional\nIf you don't provide name it will be random name\nIf you don't provide collection it will be auto configured by items\n\nurl or data should be provided" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Result Format



[block:callout] { "type": "info", "body": "Almost all parameters are optional\nIf you don't provide name it will be random name\nIf you don't provide collection it will be auto configured by items\n\nurl or data should be provided" } [/block]