Table of Content

MetaFS REST API

THIS IS A PRELIMINARY DOCUMENT

VERSION: PRELIMINARY (2016/11/03)

NOTE: This API is subject to changes until version 1.0 is declared, likely beginning 2017.

1. Introduction

metafs-rest is a standalone program which provides HTTP-based REST API, and it's launched at boot time with /etc/init.d/metafs-rest start

All communication works via HTTP GET for now, later also POST, DELETE.

By default the response header includes Content-type: application/json, and contains an JSON object: 

{
   "status": 0,                  # 0 = OK, 400 = failed
   "results": [ ... ],
   "server": {
      "uptime": 2663.21237,
      "version": "MetaFS-REST 0.1.5",
   }
}
unless you access the content direct (see below with more details).

2. Volumes

Get list of volumes in MetaFS: 

GET http://localhost:21080/

Response: 

{
   "status": <code>,
   "results": [ <volume1>, ... ],
}
Example: 
{
   "status" : 0,
   "results" : [
      "alpha",
      "beta"
   ],
   "server": {
      "uptime": 2664.323588
      "version": "MetaFS-REST 0.1.5",
   }
}

2.1. Datasets

A volume contains various datasets and can be referenced as such: GET http://host:21080/{volume}/{dataset}

You can query the datasets via GET http://host:21080/{volume}/ like:

Example: 

GET http://localhost:21080/alpha/

Response: 

{
   "status": 0,
   "results": [
      "items",
      "triggers",
      "fs",
      "versions",
   ],
   "server": {
      "uptime": 2664.323588
      "version": "MetaFS-REST 0.1.5",
   }
}

2.1.1. Primary Datasets

  • items: the actual items in the volume
  • fs: filesystem information, like mount point and creation time etc

2.1.2. Secondary Datasets

  • triggers: current trigger queue
  • statistics: handler related statistics
  • etc
essentially you can access all sub datasets created by the core of MetaFS and its handlers, GET http://host:21080/{volume}/{dataset}:

Examples: 

http://localhost:21080/alpha/items
which will list all items in a volume named "alpha".

3. Filtering

You can filter the set of entries you by different filters: http://host:21080/{volume}/{dataset}?filter, whereas the filter is composed as stringyfied JSON object:

3.1. Find

Finding items: 
{"find":{<key>: <match>}, ... }                    # simple key value matching (logical AND)
{"find":{<key>: { <qualifier>: <value> }, ... }    # complex query/find

whereas the key is the key, e.g. name or also image.pixels, special keys are:

  • location: either define city (and optionally country) or lat & long to find items
  • fts: define the word which should be searched for in the full text index/search (fts)
qualifiers:
  • $gt greater than, $gte greater or equal than
  • $lt less than, $lte less or equal than
  • $not
  • $ne not equal
  • $eq equal
  • $distinct distinct/unique values
By default the MongoDB Query Language (MQL) is supported plus extended $distinct which returns count as well.

Examples: 

http://localhost:21080/alpha/items?{"find":{"name":"AA.txt"}}
which finds all items with name: "AA.txt"

finding items with GPS coordinates: 

http://localhost:21080/alpha/items?{"find":{"location":{"city":"Zurich"}}}

finding full text index/search (fts): 

http://localhost:21080/alpha/items?{"find":{"fts":"mahabharata"}}

find images with width 500..1000 

http://localhost:21080/alpha/items?{"find":{"image.width":{"$gte":500,"$lte":1000}}

find distinct values of a key: 

http://localhost:21080/alpha/items?{"find":{"tags":{"$distinct":1}}}
giving 
"results": [
   { 
      "tags": "red",
      "count": 22
   },
   {
      "tags": "blue",
      "count: 18
   },
   ...
]

3.2. Sort

Sorting results: 
{"sort":{<key>: dir}}
whereas dir is either -1 (descending order) or 1 (ascending order, default)

Examples: 

http://localhost:21080/alpha/items?{"find":{"name":"AA.txt"},"sort":{"utime":-1}}
Sorts found entries utime (update time) in descending order (newest first).

3.3. Limit

Limiting results: 
{"limit":<count>}
Examples: 
{"limit":10}
Limit to 10 entries.

3.4. Skip

Skipping results: 
{"skip":<count>}
Examples: 
http://localhost:21080/alpha/items?{"find":{"name":"AA.txt"},"skip":10}
Skip first 10 entries.

The combination of limit and skip allows nice pagination: 1-10, 11-20, 21-30 etc

3.5. Count

Count actual hits regardless of limit: 
{"count":0|1}
Examples: 
http://localhost:21080/alpha/items?{"find":{"name":"AA.txt"},"limit":10,"count":1}
gives 
{
   "count": 192,
   "results": [ ],
   "server": {
      ...
   }
}

3.6. Combination of Filtering

You can combine find, sort, limit and skip, such as: 
http://localhost:21080/alpha/items?{"find":{"name":"README.md"}}
http://localhost:21080/alpha/items?{"sort":{"utime":-1}}
http://localhost:21080/alpha/items?{"sort":{"utime":-1},"skip":200,"limit":50}

4. Content Access

You can access the actual content via http://host:21080/{volume}/{path}/.. which gives direct access to /var/lib/metafs/volumes/{volume}/{path}/...

Examples:

Access content of an item:[1] 

http://localhost:21080/alpha/files/20/91/80c98a48ad36ec29748eb84b72b7a6c4db9d93041ed8f1344bc2453c692b
The thumbnail of the same item, as referenced in thumb.src: 
http://localhost:21080/alpha/thumb/20/91/80c98a48ad36ec29748eb84b72b7a6c4db9d93041ed8f1344bc2453c692b

  1. this method will change soon

5. Authentication

Currently the API does not provide any authentication, only local access (localhost) is available.

6. Updates

Significant updates of this document: Authors