It's possible to list images and their metadata in your organization and also filter by their metadata. The filter options are pretty basic right now, but may be improved in the future.
Listing source images allows searching and sorting of images. The images are by default sorted by their created date in a descending order (latest first).
Be aware: newly uploaded images or changed metadata may take a few seconds until they appear in the results.
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization'
Example JSON response:
{
"total": 126,
"links": {
"next": {
"href": "/sourceimages/myorganization?limit=100&offset=100"
}
},
"items": [
{
"binary_hash": "binaryimage-sha1hash",
"created": "2017-01-18T14:10:40+0000",
"dynamic_metadata": {},
"format": "jpg",
"hash": "sha1hash",
"height": 42,
"link": "/sourceimages/myorganization/sha1hash",
"name": "somename.jpg",
"organization": "myorganization",
"size": 84,
"width": 42
},
// ... more images
}
Where:
- total is the total amount of items matched by the search;
- links contains helpful links for pagination purposes (like prev and next for pagination)
You can limit the number of returned items of the list by using the limit and the offset parameters,
those can be used to page through results, too.
| Attribute | Description | Default |
|---|---|---|
| limit | Optional limit | 100 |
| offset | Optional offset | 0 |
Where limit must be an integer number between 0 and 2000.
Please notice that using limit=0 will return an empty list of items, but can be used to validate the
provided search parameters or for just get the total result count.
curl -X GET 'https://api.rokka.io/sourceimages/myorganization?limit=20&offset=100'
Example JSON response:
{
"total": 126,
"links": {
"next": {
"href": "/sourceimages/myorganization?limit=20&offset=120"
},
"prev": {
"href": "/sourceimages/myorganization?limit=20&offset=80"
}
},
"items": [
// ... Image objects
]
}
If you want to page beyond 10'000 hits, you need to use a so-called cursor. With a cursor you can only page forward by one "page" and not randomly access a page.
You can use this cursor value as input for the offset parameter to page to the next page. A link to the next page is provided in every response.
If you don't submit an offset number and your result has more than 10'000 hits, it will automatically return a link for the next page with the cursor value in it.
A typical response for an organization with more than 10'000 hits looks like the following:
Example JSON response:
{
"total" : 74088,
"links" : {
"next" : {
"href" : "/sourceimages/myorganization?limit=100&offset=VX3_3FBUQW9KNDlQYXMyTmtDUHhOd2NtOWtOR0ptTTJRMllURXlZekl5"
}
},
"cursor" : "VX3_3FBUQW9KNDlQYXMyTmtDUHhOd2NtOWtOR0ptTTJRMllURXlZekl5",
"items": [
// ... Image objects
]
}
You can filter the list by the fields returned by a sourceimage (and its user defined metadata). Just append the field-name and value to your list request.
The following returns all images with height = 1200.
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization?height=1200'
The following fields are available for each image for filtering:
- hash (string): the image hash;
- binaryhash (string): the image binary-hash;
- size (integer): the image filesize, in bytes;
- format (string): the image format, as the file extension ("png", "jpg");
- width (integer): the image width, in pixels;
- height (integer): the image height, in pixels;
- created (date): the image creation date;
You can also filter by fields defined in the User Metadata,
those fields are accessible by using the user: and the correct field type prefixes.
The following example will return all images where the field my_integer_field has a value of 3:
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization?user:int:my_integer_field=3'
Returning all images which start with a certain value in a field is as easy as appending a star:
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization?name=plan*'
Returns all images having their name starting with "plan", such as "plant", "plane".
If you want to filter for certain ranges or "greater than, less than", you can use the Lucene range query syntax.
Some example usage:
size=[30000,40000]: Matches images with a size value between 30000 and 40000 (extremes included)size=[30000,}: Returns images with a size value equal or bigger than 30000:size={30000,}: Matches images with a size value bigger than 30000created=['2017-01-01T00:00:00Z',}: Images created from 2017 to nowYou can filter in different fields at once, eg. size=[30000,}&name=foo* returns all images greater than
30000 and with a name starting with foo.
OR and NOT filters are currently not possible. If you have a need for that, get in contact with us and we'll see what we can do.
You can change the sort field by using the sort parameter, it accepts a field name and
(optionally) the sorting direction (as "desc" or "asc").
The following will return the items sorted by the image size, ascending:
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization?sort=size'
Default sort order is descending; if you want to change it, add desc or asc to
your sort field, eg. the biggest images first:
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization?sort=size desc'
Sorting by multiple fields is possible, just add multiple sorting criteria separated by comma.
The following example will sort images first by create descending and later by size ascending:
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization?sort=created desc,size asc'
User-Metadata fields can be used for sorting by using the prefix naming convention as for the
filtering: both the user: and the field type prefix must be specified.
The following will sort by the user defined field my_integer_field in a descending order:
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization?sort=user:int:my_integer_field desc'