{"_id":"54b933914ba4e40c00624837","user":"54352decadf50e0800b89024","project":"543d1e263a300f20000d31fb","category":{"_id":"543d1e5f5276641a00a593d0","version":"543d1e5e5276641a00a593cf","pages":["543d1e5f5276641a00a593d1","54b922801f830d0b00816011","565c82e7ea82b00d00f949f5","565c83fd2206890d00ba0492"],"__v":4,"project":"543d1e263a300f20000d31fb","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-14T12:59:18.358Z","from_sync":false,"order":0,"slug":"documentation","title":"Documentation"},"__v":1,"parentDoc":null,"version":{"_id":"543d1e5e5276641a00a593cf","forked_from":"543d1e263a300f20000d31fe","project":"543d1e263a300f20000d31fb","__v":16,"createdAt":"2014-10-14T13:00:14.946Z","releaseDate":"2014-10-14T13:00:14.946Z","categories":["543d1e5f5276641a00a593d0","543d1ee45276641a00a593da","5448e2cbc64edd1a00453c29","5449135acdc944220048845c","544a0a93778b3e08002b2289","544a0a9727b7fc140078da58","544a456f27b7fc140078daff","544e027cbd51b9080037f680","544e029ab80812080035bba6","544e3a2eb80812080035bd67","5450b7c5a66f020800dba7b3","5450c0e47abbbc0800a5e989","5450c0f97abbbc0800a5e98a","5450c103a66f020800dba819","54f99f588d09b7390007ea45","565c81dbf3e9360d00823e43"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-01-16T15:51:45.929Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"API v2 hands you the freedom to combine different parameters in new and interesting ways.\n\nThis freedom comes at a cost though; some things might not be immediately clear.\nOn this page we'll try to explain a few common pitfalls, and hand out a few paragraphs on best practice.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Arguments to list endpoints are AND'ed together\"\n}\n[/block]\nAlmost all of our list endpoints work in the same way.\nThey provide access to all of our active data, and depending on the arguments\nyou give them, irrelevant content will be filtered away.\n\nThis is true for all arguments to list endpoints, even when your arguments are content ids you want to look up.\nWhat this means is that the rules of pagination and filter combination still applies, even when your arguments are a list of ids to fetch.\n\nWhat does this mean? Let's take an example:\n\nSay we want to retrieve a list of stores. We know exactly what stores we need, so we query the store list with the `store_ids` argument set to the list of known ids:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /v2/stores?r_lat=55.6&r_lng=12.3&r_radius=10000&store_ids=6dfcSv,0d84ov HTTP/1.1\\nHost: api.etilbudsavis.dk\\nAccept: application/json, */*; q=0.01\\nX-Token: 00i4zpsy9dqiortg\\nX-Signature: b8b2eed3d9c5ae0f8f9f7b9428f02ab5\\nUser-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1)\\n\\n\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nAnd we get a response back with a list of 2 stores. Great, so when we request 2 stores with `store_ids` we get 2 stores back, right? Not quite.\n\nAll filters are AND'ed together (i.e. All filters must match a piece of content for the content to be shown). So even if you provide a list of `store_ids`, all other criteria must also match for content to show up.\n\nLet's use the above example again, but this time decrease the distance to 0:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"GET /v2/stores?r_lat=55.6&r_lng=12.3&r_radius=0&store_ids=6dfcSv,0d84ov HTTP/1.1\\nHost: api.etilbudsavis.dk\\nAccept: application/json, */*; q=0.01\\nX-Token: 00i4zpsy9dqiortg\\nX-Signature: b8b2eed3d9c5ae0f8f9f7b9428f02ab5\\nUser-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1)\\n\\n\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nNow the above request will return an empty list. This is because that even though stores match the given `store_ids`, none of them are below 0 meters from the given point. Obviously the above query is never useful, but illustrates that you as the developer are responsible for making the queries sane.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Pagination is always on!\"\n}\n[/block]\nRelated to the above gotcha; list **pagination is always on**. Even if you don't specify a `limit` argument yourself.\n\nIf the limit is 24 (that is the common default for content lists) you'll never get more than 24 items back. Even if you specify 100 stores with `store_ids` in the above example, you will only - at most - get the first 24. Which ones you'll get is determined by sort order, which is also always on. You can see the default values for both `order_by` and `limit` for each endpoint.","excerpt":"Things to keep in mind when building with the eTilbudsavis API v2","slug":"gotchas-dos-and-donts","type":"basic","title":"Gotchas, Do's and Don'ts"}

Gotchas, Do's and Don'ts

Things to keep in mind when building with the eTilbudsavis API v2

API v2 hands you the freedom to combine different parameters in new and interesting ways. This freedom comes at a cost though; some things might not be immediately clear. On this page we'll try to explain a few common pitfalls, and hand out a few paragraphs on best practice. [block:api-header] { "type": "basic", "title": "Arguments to list endpoints are AND'ed together" } [/block] Almost all of our list endpoints work in the same way. They provide access to all of our active data, and depending on the arguments you give them, irrelevant content will be filtered away. This is true for all arguments to list endpoints, even when your arguments are content ids you want to look up. What this means is that the rules of pagination and filter combination still applies, even when your arguments are a list of ids to fetch. What does this mean? Let's take an example: Say we want to retrieve a list of stores. We know exactly what stores we need, so we query the store list with the `store_ids` argument set to the list of known ids: [block:code] { "codes": [ { "code": "GET /v2/stores?r_lat=55.6&r_lng=12.3&r_radius=10000&store_ids=6dfcSv,0d84ov HTTP/1.1\nHost: api.etilbudsavis.dk\nAccept: application/json, */*; q=0.01\nX-Token: 00i4zpsy9dqiortg\nX-Signature: b8b2eed3d9c5ae0f8f9f7b9428f02ab5\nUser-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1)\n\n", "language": "http" } ] } [/block] And we get a response back with a list of 2 stores. Great, so when we request 2 stores with `store_ids` we get 2 stores back, right? Not quite. All filters are AND'ed together (i.e. All filters must match a piece of content for the content to be shown). So even if you provide a list of `store_ids`, all other criteria must also match for content to show up. Let's use the above example again, but this time decrease the distance to 0: [block:code] { "codes": [ { "code": "GET /v2/stores?r_lat=55.6&r_lng=12.3&r_radius=0&store_ids=6dfcSv,0d84ov HTTP/1.1\nHost: api.etilbudsavis.dk\nAccept: application/json, */*; q=0.01\nX-Token: 00i4zpsy9dqiortg\nX-Signature: b8b2eed3d9c5ae0f8f9f7b9428f02ab5\nUser-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1)\n\n", "language": "http" } ] } [/block] Now the above request will return an empty list. This is because that even though stores match the given `store_ids`, none of them are below 0 meters from the given point. Obviously the above query is never useful, but illustrates that you as the developer are responsible for making the queries sane. [block:api-header] { "type": "basic", "title": "Pagination is always on!" } [/block] Related to the above gotcha; list **pagination is always on**. Even if you don't specify a `limit` argument yourself. If the limit is 24 (that is the common default for content lists) you'll never get more than 24 items back. Even if you specify 100 stores with `store_ids` in the above example, you will only - at most - get the first 24. Which ones you'll get is determined by sort order, which is also always on. You can see the default values for both `order_by` and `limit` for each endpoint.