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.
Pagination
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.
/v3/assets?_page=2&_pageSize=25
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.
Sorting
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.
/v3/assets?_sort=asc&_sortBy=title
OR
/v3/assets?_sort=desc&_sortBy=title
Query Operators
Equality
To search for resources where a field in the resource equals an exact value, you can use:
/v3/assets?type=video
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:
/v3/assets?type={"neq":"video"}
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:
/v3/assets?title={"ct":"oscar"}
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:
/v3/assets?duration={"bt":"10000..60000"}
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
/v3/assets?duration={"gt":"10000"}
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
/v3/assets?duration={"lt":"10000"}
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
/v3/assets?uploadedBy={"in":"susan,jim"}
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
/v3/assets?tags={"nin":"susan,jim"}
The above example will return all assets that we uploaded by anyone other than susan or jim
A couple important things to consider
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.
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.
Response Headers
The MediaSilo API returns response headers with each request.
Access-Control-Allow-Origin → *
Client-IP-Address → 50.195.210.21
Connection → keep-alive
Content-Type → application/json
Link → <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"
Server → Jetty(9.1.z-SNAPSHOT)
X-RateLimit-Limit → 10000
X-RateLimit-Remaining → 9969
X-RateLimit-Reset → 1421704672
total-results → 3914
transfer-encoding → chunked
| Header | Description |
|---|---|
| Client-IP-Address | The IP address of the client request |
| Content-Type | Usually application/json |
| Link | Contains the fully qualified links for retrieving the previous or next page for the request. Only applies to paged content. |
| X-RateLimit-Limit | The number of remaining API queries for the current time span. Accounts default to 10,000 requests per hour. |
| X-RateLimit-Reset | Specific time when the rate limit is reset, usually once per hour. |
| total-results | Total results in the query set. For paged content, this is useful for creating a pagination footer. |