============================================ Learning Registry - Slicing ============================================ **Document Version: 1.0** **Last Edited: September 14 , 2011** Prepared by: John Brecht, SRI International (john.brecht@sri.com) .. figure:: images/cc-by-nc-sa.jpg :align: center :alt: Creative Commons Attribution NonCommercial ShareAlike 3.0 Unported License Copyright 2011 - SRI International This work is licensed under the `Creative Commons Attribution NonCommercial ShareAlike 3.0 Unported License. `_ ------------ Introduction ------------ The Slice service provides a mechanism via which Learning Registry users may retrieve a subset of Resource Description Data available at a given node. Presently, the Slice service handles the following parameters: - **Date Range**: Matching against node\_timestamp, but at the granularity of a day - **Identity**: Matching any of the four possible identities: submitter, curator, owner, or signer - **Tags**: Matching any of a document's keys, schema type, or resource data type. Any combination of either Date Range and Identity or Date Range or Tags may be passed to the Slice services and are effectively ANDed together. That is, if a date range, and tag are passed to Slice, resultant documents will have been published: within that date range and has a key, schema type, or resource data type matching that tag. Furthermore, multiple tags may be specified, with the results being that the tags are ORed together. That is, if both “mathematics” and “metadata” are specified in the list of tags, documents will be returned that have either or both of those terms. Thus, results have: date AND identity OR date AND (tag1 OR tag2 OR tag3 ...) Date range is specified with a start date (“from”) and end date (“until”). Those dates and all dates in between are OR’d together as follows: (from OR date2 OR date3 OR ... until) AND identity AND (tag1 OR tag2 OR tag3 ...) If one specific date is wanted, then only start date (“from”) is specified. Again, any combination of the three parameters may be passed, so users may Slice for: date identity tags date AND identity date AND tags Future implementations MAY allow for multiple identities and for tags to be ANDed. ~~~~~~~~~~~~~~~~~~~~~~ IDs vs. Full Documents ~~~~~~~~~~~~~~~~~~~~~~ The user may also specify a Boolean argument ‘ids\_only’. If true, only doc IDs are returned, otherwise full Resource Data Description documents are returned. ~~~~~~~~~~~~ Flow Control ~~~~~~~~~~~~ Some Learning Registry nodes will have Flow Control enabled for Slice. This means that the node administrator can specify a cap on the number of results returned for a given query. In such cases, when results are returned, they will include a “resumption\_token” field. The value of this field is a token that can be used as an argument to re-slice the node, in which case, in which case the next page of results is returned. (To set Flow Control parameters, node administrators should run /config/services/Slice.py and they will be led through a series of prompts to specify the values.) ------- API ------- .. http:get:: /slice :query from: *(date)* date of publication to learning registry in the form: YYYY-MM-DD, optional :query until: *(date)* date of publication to learning registry in the form: YYYY-MM-DD, optional :query identity: *(string)* the name of a person or organization that is the submitter, author, owner, or curator Case-insensitive, but full string match only, optional :query any_tags: *(list of string)* list of tags, matched against keys, payload\_schema, or resource\_data\_type. Case-insensitive, but full string match only, optional :query ids_only: *(boolean)* whether to return only a list of IDs or a list of full documents, optional, default is false :query resumption_token: *(string)* a token received from a previous query that instructs the node to return the next page of results for that query, optional **Example Usage** .. sourcecode:: http http:///slice?start_date=&any_tags=,,... http://&identity= **Response Object:** .. sourcecode:: http { “documents”: [ // array of resource data description documents { “doc\_ID”: “string”, // ID of the document "resource\_data\_description": {resource data description document} //complete document } ], "resumption\_token": "string", // the token used to resume the next page of // results when flow control is used "resultCount": “integer” // the total number of results for this set of // query parameters, regardless of flow control } OR, if ``ids_only`` is true: .. sourcecode:: http { “documents”: [ // array of document IDs { “doc\_ID”: “string”, // ID of the document } ] } ------------------------- Usage Examples ------------------------- ``http:///slice?any_tags=Arithmetic`` Returns - documents containing “Arithmetic” as a key word ``http:///slice?any_tags=paradata&identity=CTE%20Online&full_docs=true`` Returns - paradata documents submitted/owned/curated/signed by CTE Online, including full docs instead of just IDs ``http:///slice?from=2011-06-10`` Returns - all Resource Data Descriptions submitted on June 10th, 2011 ``http:///slice?any_tags=paradata&identity=CTE%20Online&from=2011-06-10&full\_docs=true`` Returns - full docs of paradata submitted by CTE Online on June 10th, 2011 ``http:///slice?any_tags=french,spanish,german`` Returns - IDs of docs containing either ‘french’, ‘spanish’, or ‘german’ keywords. ``http:///slice?any_tags=french,spanish,german&resumption_token=eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJrZXlzIjogWyJtYXRoZW1hdGljcyJdLCAib2Zmc2V0IjogMTAwfQ.Zj05MgBHDJFrivmHjawnrV3EiFej_jllHOIEdiMnOoo`` Returns - The next page of results for the above query, where the token specified came as part of the result object for a previous query ``http:///slice?from=2011-05-27&until=2011-06-14&any_tags=arithmetic`` Returns - IDs of docs containing the keyword ‘arithmetic’ and were received by the Learning Registry between May 27th and June 14th 2011.