MindTouch Community Portal
Logged in: Logged in as: Log in
Register
Search:
Page last modified 22:39, 12 Sep 2010 by MaxM
User:dev > Specs > Property collections
Page Notifications Off

Property collections

    Purpose

    A lightweight filterable collection of like-data within properties 
     

    Intended Audience

    This is a feature intended for users and developers that extend and build on top of MindTouch. End users are not meant to directly interact with this feature via the UI.

    Status

    2 Aug 2010: Initial scoping and brainstorming

    3 Aug 2010: Completed initial draft for design of API features 

    4 Aug 2010: Added some practical use cases

    13 Sep 2010: Updated spec to better match implementation (took out <contents> element and metadata from items)

     

    Use Cases

    • A task list. New tasks are easy to add. Updating the status of one or more tasks is simple. Filtering your tasks by a status, date range, or category.
    • A guestlist or appointments. Easy to add your name or appointment to a list without having to repost the entire set. Change your mind or want to update? You may delete your entry or update it without affecting others.
    • A maintainable list of interests of skills. A UI can be built to easily add, update, filter, and remove items from the list. 

    Functional Specification

    MimeType
    This set of features only activates for properties with the following mimetype:
    ContentType: application/xml; propertycollection=true
    Accessing these features for properties with other mimetypes returns a (400) BadRequest.
     
    Filtering
    Each item may have key=value pairs represented by attributes within an item. These may be used to store simple text or numeric data that may then be used for filtering items as well as sorting. Items may be filtered by using the built in xpath engine based on their attributes.
    Item Content

    Each item may have content associated with it other than the attributes. This is limited to text based storage including (x)html, xml, json, etc.

    Paging and sorting
    Items may be paged using limit and offset. Sorting may be performed on a named item attribute. 
    Revisioning

    Since items are stored as properties which are revisioned upon any content changes, the same applies for property collections. Adding, updating, and removing an item causes the property to be updated which creates a new revision with the new set of items. Performing these operations in batch when applicable allows meaningful change tracking of the items by grouping like-operations together. Unfortunately there's not yet support for retrieving older property revisions via the REST API.

     
    Non-Goals
    • No storage of binary data will be allowed into property items (at least for now)
    • No support for concurrency control other than guaranteeing atomicity for batch changes
     

    Technical Specification

    API Features

    Get items by a query
    GET: {resource}/properties/{key}/items
      ?q="id < 6"
      &limit=2
      &offset=0
      &sort=-year
    <items count=2 querycount=5 totalcount=10 href={uri to query}>
 <item id="1" type="car" make="mazda" class="wagon" model="protege5" year="2002">Showing some age but tons of character!</item>
 <item id="2" type="moto" make="suzuki" class="sport-turing" model="sv650" year="2001"/>
</items>
    All items are retrieved by default but may be filtered, paged, and sorted.
    Add and/or update one or more items
    POST: {resource}/properties/{key}/items
     ContentType: application/xml; propertycollection=true
     Input: One or more items. Example:
    <items>
  <!-- new item with no content -->
  <item type="plane" make="boeing" model="B777"/>

  <!-- update existing item and its content -->
  <item id="2" type="car" make="mazda" class="sportswagon" model="protege5" year="2002">The item body and attributes may be updated</item>
</items>

    Providing an item id updates an existing item including its attributes and body. Omitting an id creates a new item with a generated id. Id's may be created by the client and if no matching id exists then a new item is created having the given id.

    This feature also supports adding an item without the XML envelope. Specify the item's ContentType (such as application/json, or application/xml), content as message body, and attributes as query parameters. This way a client may add an item without needing to encode it for inclusion into XML. An item may be updated like this by specifying its id as a query parameter.

    Remove one or more items
    DELETE: {resource}/properties/{key}/items?q="id = 5"
     

    TODO:

    • tweak the ContentType for property collections
    • Changes to XML for GET:{resource}/properties/ and GET:{resource}/properties/{key}/info to describe that it's a property collection. 
    • Consider item metadata: date.modified, user.modified
    • DekiScript methods to allow item retrieval with filtering, paging, sorting 
    • Consider supporting JSON as well as XML for adding and updating items in batch via POST: {resource}/properties/{key}/items
    • Consider atom output format
    • Discuss optimistic concurrency via etag support
    • Upload a binary of the service finally!!
    Tag page
    What links here

    Files 1

    Attach file or image
    FileVersionSizeModified 
    Viewing 2 of 2 comments: view all
    #1
    Guerric says:
    How is unique-ness determined? What about accepting json as a format?
    Posted 14:48, 2 Aug 2010
    #2
    MaxM says:
    @guerric
    each item gets a server generated unique id upon addition. Any non-binary content bodies should be ok including json.
    Posted 15:25, 2 Aug 2010
    Viewing 2 of 2 comments: view all
    You must login to post a comment.
    MindTouch Social Knowledge Base

    Copyright © 2011 MindTouch, Inc. Powered by