{"__v":17,"_id":"54370fa726469424002a6e19","category":{"__v":8,"_id":"54343531bfaa3d0800c4d4b0","pages":["54349c225b10711400c6c539","54349c905b10711400c6c53b","54370bea4e799808006da391","54370fa726469424002a6e19","5480aad4e952bb1a006b320c","5638d6c12fc5520d001a4cc9","568fe01b21fcf0190071d8fb"],"project":"54343170fa5527080064f449","version":"54343531bfaa3d0800c4d4af","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-07T18:31:12.137Z","from_sync":false,"order":0,"slug":"documentation","title":"Documentation"},"is_link":false,"parentDoc":null,"project":"54343170fa5527080064f449","user":"543532513513400800a144f4","version":{"__v":27,"_id":"54343531bfaa3d0800c4d4af","forked_from":"54343170fa5527080064f44c","project":"54343170fa5527080064f449","createdAt":"2014-10-07T18:47:13.086Z","releaseDate":"2014-10-07T18:47:13.086Z","categories":["54343531bfaa3d0800c4d4b0","543435b1edce040800409240","543435b9edce040800409241","543435bcedce040800409243","543435bfedce040800409244","543435c2edce040800409245","54370cc426469424002a6dfa","54370cf026469424002a6dfd","5437129d26469424002a6e2f","543712d226469424002a6e30","5480c8fd74904f1a00053c86","54aafc6eefb39016009e4d71","54ac1d36de18cc1400226e01","54ad59369219922100751732","54b41bcf4f25cb1600518d2c","54b533a3a806f40c0050d53c","54b54bbf96fe3c0b00d38d2a","54b688a27379a90c00f53a8a","54b699efbc1a46160005edfa","54b8191691011f0b00068804","54bfb002d03bfc0d0000e814","54bfb33ed03bfc0d0000e816","55a3e94e912a6e2300882cdb","55a56c370f354f0d00fd02a8","55e85ad034516037002e9325","5638ecb62fc5520d001a4cf9","572cba2fc310640e008f63d5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3.0"},"updates":["54b58df72d48f3350040e597"],"next":{"pages":[],"description":""},"createdAt":"2014-10-09T22:43:51.914Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"try":true,"auth":"never","params":[],"url":""},"isReference":false,"order":3,"body":"In addition to dealing with resources by ID (eg. \"/v3/myresource/[SOME_ID]\") the MediaSilo API also supports querying for multiple resources by way of query parameters. You can specify criteria, pagination, and sorting. Querying support is available for most of our resource endpoints.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Pagination\"\n}\n[/block]\nTo specify the number of results that are returned, you can use the \"_page\" and \"_pageSize\" query parameters to specify the page index and total results per page that you'd like returned.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v3/assets?_page=2&_pageSize=25\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nYour results will include the total number of results in the response header \"total-results\". It will also include links to the first, next, and last pages in the \"Link\" header.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sorting\"\n}\n[/block]\nYou can order the results that are returned to you by passing the \"_sort\" and \"_sortBy\" parameters, which specify the directional order and field to sort by.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v3/assets?_sort=asc&_sortBy=title\\nOR\\n/v3/assets?_sort=desc&_sortBy=title\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Query Operators\"\n}\n[/block]\n**Equality**\n\nTo search for resources where a field in the resource equals an exact value, you can use:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v3/assets?type=video\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nThe above example will only return assets whose type is video.\n\n**Inequality**\n\nTo search for resources where a field in the resource does not equal some value, the following can be used:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v3/assets?type={\\\"neq\\\":\\\"video\\\"}\",\n      \"language\": \"http\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\nThe above example will return all assets that are NOT a video.\n\n**Contains**\n\nTo search for resources where a field in the resource contains some value, the following can be used:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v3/assets?title={\\\"ct\\\":\\\"oscar\\\"}\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nThe above will return any assets that contain \"oscar\" in the title.\n\n**Range**\n\nTo search for resources with a field that exists between two values, the following can be used:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v3/assets?duration={\\\"bt\\\":\\\"10000..60000\\\"}\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nThe above will return any assets whose duration is between 10 and 60 seconds.\n\n**Greater Than**\n\nTo search for assets with a field that is greater than some value, the following can be used\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v3/assets?duration={\\\"gt\\\":\\\"10000\\\"}\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nThe above example will return all assets whose duration is more than 10 seconds.\n\n**Less Than**\n\nTo search for assets with a field that is less than some value, the following can be used\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v3/assets?duration={\\\"lt\\\":\\\"10000\\\"}\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nThe above example will return all assets whose duration is less than 10 seconds.\n\n**In**\n\nTo search for a resource with a field where the value can be any value in a list, the following can be used\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v3/assets?uploadedBy={\\\"in\\\":\\\"susan,jim\\\"}\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nThe above example will return all assets that we uploaded by either susan or jim.\n\n**Not In**\n\nTo search for a resource with a field where the value cannot be any value in a list, the following can be used\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v3/assets?tags={\\\"nin\\\":\\\"susan,jim\\\"}\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nThe above example will return all assets that we uploaded by anyone other than susan or jim\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"* Query parameters are supported for root level fields on a resource. If you have a resource that has child objects, the child object and the fields contained within it are not queryable.\\n\\n* Querying is limited to your scope. No matter what you ask for, it will be limited by what you have access to. For example, if you query for all video assets in a project that you are not a part of, you will not receive any results.\",\n  \"title\": \"A couple important things to consider\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response Headers\"\n}\n[/block]\nThe MediaSilo API returns response headers with each request. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Access-Control-Allow-Origin → *\\nClient-IP-Address → 50.195.210.21\\nConnection → keep-alive\\nContent-Type → application/json\\nLink → <http://p-api-new.mediasilo.com/v3/assets/?_pageSize=10&_page=391>; rel=\\\"last\\\",<http://p-api-new.mediasilo.com/v3/assets/?_pageSize=10&_page=2>; rel=\\\"next\\\"\\nServer → Jetty(9.1.z-SNAPSHOT)\\nX-RateLimit-Limit → 10000\\nX-RateLimit-Remaining → 9969\\nX-RateLimit-Reset → 1421704672\\ntotal-results → 3914\\ntransfer-encoding → chunked\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Header\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"Client-IP-Address\",\n    \"0-1\": \"The IP address of the client request\",\n    \"1-0\": \"Content-Type\",\n    \"1-1\": \"Usually *application/json*\",\n    \"2-0\": \"Link\",\n    \"2-1\": \"Contains the fully qualified links for retrieving the previous or next page for the request. Only applies to paged content.\",\n    \"3-0\": \"X-RateLimit-Limit\",\n    \"3-1\": \"The number of remaining API queries for the current time span. Accounts default to 10,000 requests per hour.\",\n    \"4-0\": \"X-RateLimit-Reset\",\n    \"4-1\": \"Specific time when the rate limit is reset, usually once per hour.\",\n    \"5-0\": \"total-results\",\n    \"5-1\": \"Total results in the query set. For paged content, this is useful for creating a pagination footer.\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]","excerpt":"Describes how to request resources using URL query parameters","slug":"restful-querying","type":"basic","title":"RESTful Querying"}

RESTful Querying

Describes how to request resources using URL query parameters

In addition to dealing with resources by ID (eg. "/v3/myresource/[SOME_ID]") the MediaSilo API also supports querying for multiple resources by way of query parameters. You can specify criteria, pagination, and sorting. Querying support is available for most of our resource endpoints. [block:api-header] { "type": "basic", "title": "Pagination" } [/block] To specify the number of results that are returned, you can use the "_page" and "_pageSize" query parameters to specify the page index and total results per page that you'd like returned. [block:code] { "codes": [ { "code": "/v3/assets?_page=2&_pageSize=25", "language": "http" } ] } [/block] Your results will include the total number of results in the response header "total-results". It will also include links to the first, next, and last pages in the "Link" header. [block:api-header] { "type": "basic", "title": "Sorting" } [/block] You can order the results that are returned to you by passing the "_sort" and "_sortBy" parameters, which specify the directional order and field to sort by. [block:code] { "codes": [ { "code": "/v3/assets?_sort=asc&_sortBy=title\nOR\n/v3/assets?_sort=desc&_sortBy=title", "language": "http" } ] } [/block] [block:api-header] { "type": "basic", "title": "Query Operators" } [/block] **Equality** To search for resources where a field in the resource equals an exact value, you can use: [block:code] { "codes": [ { "code": "/v3/assets?type=video", "language": "http" } ] } [/block] The above example will only return assets whose type is video. **Inequality** To search for resources where a field in the resource does not equal some value, the following can be used: [block:code] { "codes": [ { "code": "/v3/assets?type={\"neq\":\"video\"}", "language": "http", "name": null } ] } [/block] The above example will return all assets that are NOT a video. **Contains** To search for resources where a field in the resource contains some value, the following can be used: [block:code] { "codes": [ { "code": "/v3/assets?title={\"ct\":\"oscar\"}", "language": "http" } ] } [/block] The above will return any assets that contain "oscar" in the title. **Range** To search for resources with a field that exists between two values, the following can be used: [block:code] { "codes": [ { "code": "/v3/assets?duration={\"bt\":\"10000..60000\"}", "language": "http" } ] } [/block] The above will return any assets whose duration is between 10 and 60 seconds. **Greater Than** To search for assets with a field that is greater than some value, the following can be used [block:code] { "codes": [ { "code": "/v3/assets?duration={\"gt\":\"10000\"}", "language": "http" } ] } [/block] The above example will return all assets whose duration is more than 10 seconds. **Less Than** To search for assets with a field that is less than some value, the following can be used [block:code] { "codes": [ { "code": "/v3/assets?duration={\"lt\":\"10000\"}", "language": "http" } ] } [/block] The above example will return all assets whose duration is less than 10 seconds. **In** To search for a resource with a field where the value can be any value in a list, the following can be used [block:code] { "codes": [ { "code": "/v3/assets?uploadedBy={\"in\":\"susan,jim\"}", "language": "http" } ] } [/block] The above example will return all assets that we uploaded by either susan or jim. **Not In** To search for a resource with a field where the value cannot be any value in a list, the following can be used [block:code] { "codes": [ { "code": "/v3/assets?tags={\"nin\":\"susan,jim\"}", "language": "http" } ] } [/block] The above example will return all assets that we uploaded by anyone other than susan or jim [block:callout] { "type": "info", "body": "* Query parameters are supported for root level fields on a resource. If you have a resource that has child objects, the child object and the fields contained within it are not queryable.\n\n* Querying is limited to your scope. No matter what you ask for, it will be limited by what you have access to. For example, if you query for all video assets in a project that you are not a part of, you will not receive any results.", "title": "A couple important things to consider" } [/block] [block:api-header] { "type": "basic", "title": "Response Headers" } [/block] The MediaSilo API returns response headers with each request. [block:code] { "codes": [ { "code": "Access-Control-Allow-Origin → *\nClient-IP-Address → 50.195.210.21\nConnection → keep-alive\nContent-Type → application/json\nLink → <http://p-api-new.mediasilo.com/v3/assets/?_pageSize=10&_page=391>; rel=\"last\",<http://p-api-new.mediasilo.com/v3/assets/?_pageSize=10&_page=2>; rel=\"next\"\nServer → Jetty(9.1.z-SNAPSHOT)\nX-RateLimit-Limit → 10000\nX-RateLimit-Remaining → 9969\nX-RateLimit-Reset → 1421704672\ntotal-results → 3914\ntransfer-encoding → chunked", "language": "text" } ] } [/block] [block:parameters] { "data": { "h-0": "Header", "h-1": "Description", "0-0": "Client-IP-Address", "0-1": "The IP address of the client request", "1-0": "Content-Type", "1-1": "Usually *application/json*", "2-0": "Link", "2-1": "Contains the fully qualified links for retrieving the previous or next page for the request. Only applies to paged content.", "3-0": "X-RateLimit-Limit", "3-1": "The number of remaining API queries for the current time span. Accounts default to 10,000 requests per hour.", "4-0": "X-RateLimit-Reset", "4-1": "Specific time when the rate limit is reset, usually once per hour.", "5-0": "total-results", "5-1": "Total results in the query set. For paged content, this is useful for creating a pagination footer." }, "cols": 2, "rows": 6 } [/block]