Multi-Collection Searches

Some collection lists allow simultaneous search for assets in all collections in the collection list using a collection query. This is called a multi-collection search. A collection list which supports multi-collection searches is called searchable. The result of a multi-collection search is again a collection list, which contains all collections in which assets matching the search query were found. It is called a search collection list.

Currently, only the list of archives is searchable, i.e., it is possible to search in all archives using one request, but not in other collection lists.

A collection list is searchable if its searchURL attribute is not null. In this case, the searchURL attribute is a URL template, which may look as follows:

searchURL: "/fotoweb/archives/{?q}"

By replacing the placeholder {?q} with a collection query, one obtains the URL of the multi-collection search. The search collection list can then be requested as follows:

GET search_url
Accept: application/vnd.fotoware.collectionlist+json

This returns a Collection List representation of the search collection list. Each collection in the search result is itself a search collection, which is the result of a search using the same query in one of the collections of the original collection list.

Each entry in the collection list contains the number of assets matching the search in the assetCount attribute. This can be used immediately for displaying the number of hits in each collection.

Getting the search results in each collection is the same process as getting the assets in each archive: The client makes a separate request to the URL given by the data attribute of each collection in the search collection list that it is interested in:

GET result_collections[i].data
Accept: application/vnd.fotoware.assetlist+json

Global Searches

In addition to searchable collection lists, it is also possible to search for assets globally on the entire site. This is called global search. A global search is done in the same way as a multi-collection search, and the URL template can be found in the public API descriptor as well as in the full API descriptor:

{  ...
  "searchURL": "...",
  ...
}

Currently, a global search searches all archives and ONLY archives, so the global search URL template is the same as the search URL of the archive list.

In future versions, global searches may include collections other than archives (such as albums) as well as new kinds of collections that do not exist at this time, so an application SHOULD do a global search ONLY if it is desirable to find results in any kind of collection, whereas an application that is only interested in results in archives should do a multi-collection search in the archive list instead, even though the result would be the same in today's version of FotoWeb. In both cases, the application SHOULD NOT us a hard-coded search URL, as search URLs are subject to change. For example, in a future version, the global search URL may change from /fotoweb/archives/{?q} to something like /fotoweb/{?q}.

Full Example

For example, consider that the request user has access to the archives "Photos", "Presentations" and "Documents" and performs a multi-collection search for the term "birds".

The client first requests the API descriptor, which returns the URL of the list of archives:

GET /fotoweb/me/
Accept: application/vnd.fotoware.full-api-descriptor+json

200 OK
Content-Type: application/vnd.fotoware.full-api-descriptor+json

{
  ...
  "archives": "/fotoweb/me/archives/",
  ...
}

The client then requests the archive list, which contains the searchURL:

GET /fotoweb/me/archives/
Accept: application/vnd.fotoware.collectionlist+json

200 OK
Content-Type: application/vnd.fotoware.collectionlist+json

{
  "searchURL": "/fotoweb/archives/{?q}",
  ...
}

By replacing the placeholder {?q} with the collection query ?q=birds, the client then performs the multi-collection search as follows:

GET /fotoweb/archives/?q=birds
Accept: application/vnd.fotoware.collectionlist+json

200 OK
Content-Type: application/vnd.fotoware.collectionlist+json

{
  "data": [
    {
      "name": "Birds",
      "data": "/fotoweb/archives/5000-Birds/?q=birds",
      "assetCount": 10
      ...
    },
    {...},
    ...
  ],
  "paging": {...}
}

In this example, the "Birds" archive contains 10 assets that match the search query. To get the assets in this collection that matched the search, the client makes another request to the URL of the "Birds" archive, which it obtains from the data attribute of the "Birds" archive in the search collection list above.

GET /fotoweb/archives/5000-Birds/?q=birds
Accept: application/vnd.fotoware.assetlist+json

200 OK
Content-Type: application/vnd.fotoware.assetlist+json

{
  data: [
    {
      "filename": "cormorant.jpg",
      "href": "/fotoweb/archives/5000-Birds/Birds/cormorant.jpg",
      ...
    },
    {...},
    ...
  ],
  paging: {...}
}

NOTE: All URLs shown in this example are for illustration only. Clients should never hard-code or make any assumptions about the format of URLs.