Use cases
The Simple Search API was intended to address a limited number of use cases involving properties common to all Fedora resources such as containment relationships, modified dates, mime types, and content size to name a few.
Below is a list of examples of queries that you can run on your repository:
- All resources
- Recursively list all resources contained by a resource
- Resources containing a resource (ancestor list)
- Resources modified since a date/time
- All binary resources
- Resources of mimetype X
- Resources where md5 matches X
- Resources greater than X MBs in size
- All images greater than or equal to X MBs
API
Endpoint: http://localhost:8080/fcrepo/rest/fcr:search
Method: GET
Parameters:
Name | Type |
| Used in condition | Currently implemented |
condition | string | A condition consists of a metadata element name followed directly by an operator, followed directly by a value. Valid element names are: fedora_id, modified, created, content_size, mime_type, rdf_type Valid operators are: =, >, <, =>, <= A search URI may specify one or more conditions | N | |
fields | string | A comma separated list of fields to be returned in the search results | N | |
max_results | int | Maximum number of results to return in a single “page” | N | |
offset | int | The offset of the first result in the page. The field is used in conjunction with max_results in order to present paged results. | N | |
order_by | string | Field name to order the query by | N | |
order | string | asc or desc | N | |
format | string | The format of the results. Valid values are:
| N | |
modified | date string : Rfc 8601 | The modification date: eg 2020-05-01T20:05:14+00:00 | Y | |
created | date string : Rfc 8601 | The creation date: eg 2020-05-01T20:05:14+00:00 | Y | |
sha1 | string | The SHA-1 of the resource | Y | |
md5 | string | The MD5 of the resource | Y | |
rdf_type | string (URI) | The URI or abbreviated string representing the RDF type. Here are some examples: http://www.w3.org/ns/ldp#NonRDFSource ldp:NonRDFSource http://www.w3.org/ns/ldp#RDFSource ldp:RDFSource | Y | |
mime_type | string | The mimetype | Y | |
fedora_id | string (URI) | The fedora resource ID*. Given the resource http://localhost:8080/rest/resource1 , you may format this condition in the following three ways: fedora_id= resource1 fedora_id= /resource1 fedora_id= info:fedora/resource1 fedora_id= http://localhost:8080/rest/resource1 | Y | |
ocfl_id | string | The OCFL Object ID* | Y | |
content_size | int | The size of a resource in bytes | Y | |
ancestor | URI | URI of the ancestral resource | Y | |
ancestors | boolean | Used in conjunction with the fedora_id field. When set to true, display the ancestors. | N | |
depth | int | Indicates the depth of recursive descendents query queries. 1 would indicate just the immediate children, 2 grandchildren, 3 great-grandchildren, and so on. | N | |
descendants | boolean | Used in conjunction with the fedora_id field. When set to true, display the descendants. | Y |
*Supports the wild-card operator(*)
Anatomy of a Search Result (HTTP Response Body)
{ input_params: { conditions: [“fedora_id=*”], max_results: 10, ... }, pagination: { max_results: 10, offset: 0, ... }, results: [ { “fedora_id”: “http://localhost:8080/rest/resource1”, ... }, { “fedora_id”: “http://localhost:8080/rest/resource2”, ... }, ... ] } |
Condition Parameter
A search query may specify one or more condition parameters. A condition parameter consists of three parts: field, operation, and value. For example the condition "fedora_id is equal to /myresource" would translate to the following query parameter value:
fedora_id=/myresource where "fedora_id" is the field, "=" is the operator and "/myresource" is the object. If you specify more than one condition parameter, the query parser will assume a logical AND operator connects them. So if you have the following two conditions
fedora_id=/myresource*
mime_type=image/*
Fedora will understand this to signify "all resources where the fedora id starts with /myresource and matching resources have any image/* mime-type.
Wild Cards
The star wild-card signifier (*) can be used in conditions for simple string matching.
Examples
List all resources
GET http://localhost:8080/fcrepo/rest/fcr:search ?condition=fedora_id%3D*
List grandchildren of resource x
Query param value: ancestor=/resource1
GET http://localhost:8080/fcrepo/rest/fcr:search ?condition=fedora_id%3D/resource1&descendents=true&depth=2
List all ancestors of resource x
GET http://localhost:8080/fcrepo/rest/fcr:search ?condition=fedora_id%3D/my/fedora/resource1&ancestors=true
List fedora id, mime_types for resources where content_size > 1 megabyte.
GET http://localhost:8080/fcrepo/rest/fcr:search ?condition=content_size%3E/my/fedora/resource1&fields=fedora_id,mime_type
Return Body (JSON)
{ ... [ { “fedora_id”: “http://localhost:8080/rest/resource1”, “mime_type”: “image/jpg” }, { “fedora_id”: “http://localhost:8080/rest//resource2”, “mime_type”: “text/plain” }, ... ] } |