Fluidinfo API Reference

On this page you will find detailed information about all Fluidinfo HTTP methods. Please note: The example API calls and responses shown below are currently only syntactically correct examples. The tags used are not guaranteed to exist (we plan to change that). A description of the functionality of the HTTP API in general can be found here. Typographic conventions used on this page are listed at bottom.

Here is the full set of HTTP API endpoints and all the methods for each:

/about: POST, GET, HEAD, PUT, DELETE.
/namespaces: POST, GET, PUT, DELETE.
/objects: POST, GET, HEAD, PUT, DELETE.
/permissions: POST, GET, PUT, DELETE.
/recent: GET.
/tags: POST, GET, PUT, DELETE.
/users: GET.
/values: GET, PUT, DELETE.

About

POST

|top

Create a new object.

POST /about/aboutstr

Create a new object with the given about value. If there is already a Fluidinfo object whose fluiddb/about tag has the given value, the returned object id will be that of the pre-existing object. In this call, and all others with an about value in the URI, you must convert your about value to UTF-8 and then percent-encode it before adding it to the request URI. You must provide valid credentials for this call to succeed. For an example see the PUT request, below.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
URI unicode string The URI of the new object.
id unicode string The id of the new object.

Example

Create an object with an about tag of 'chewing-gum'.

Request

POST /about/chewing-gum HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Type: application/json

Response

HTTP/1.1 201 Created
Content-Length: 134
Location: http://fluiddb.fluidinfo.com/about/chewing-gum
Date: Mon, 02 Aug 2010 13:00:29 GMT
Content-Type: application/json

{"id": "9c8e4b12-4b7d-40d2-865b-d5b1945350b1",
"URI": "http://fluiddb.fluidinfo.com/about/chewing-gum"}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
The aboutstr argument was not valid UTF-8. 400 (Bad Request)
An error with the request payload. More details. 400 (Bad Request)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
If valid credentials are not provided. 401 (Unauthorized)
A new object was created without error. 201 (Created)

GET

|top

The GET method for /about retrieves information about the Fluidinfo object (if any) with a particular fluiddb/about value, or retrieves the value of a tag on the object with a given about tag value.

GET /about/aboutstr

To request information on the object whose fluiddb/about tag is aboutstr, specify the about value in the request URI.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
id unicode string The id of the object.
tagPaths list of unicode strings The full path names of the tags on this object (for which the user has READ permission), if any.

Example

Retrieve information about the Fluidinfo object whose fluiddb/about value is 'Barcelona'.

Request

GET /about/Barcelona HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 1080
Date: Mon, 02 Aug 2010 13:16:09 GMT
Content-Type: application/json

{"tagPaths": ["esteve/opinion", "terrycojones/favorite-cities"]}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
The aboutstr argument was not valid UTF-8. 400 (Bad Request)
No object with the given about value exists. 404 (Not Found)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
No error occurred. 200 (OK)
GET /about/aboutstr/namespace1/namespace2/tag

Retrieve the value of a tag from the object (if any) whose fluiddb/about is aboutstr. The value is returned in the payload of the response. Please see here for more details.

Example

Return a primitive value type from Fluidinfo. Note that the Content-Type header in the response is application/vnd.fluiddb.value+json as given to Fluidinfo when the value was originally PUT.

Request

GET /about/London/geo/latitude HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 4
Date: Mon, 02 Aug 2010 13:20:31 GMT
Content-Type: application/vnd.fluiddb.value+json

51.5

Example

Return an opaque value type from Fluidinfo. Note that the Content-Type header in the response is application/pdf, because the tag value is of that type, as given to Fluidinfo when the value was originally PUT.

Request

GET /about/Barcelona/lonelyplanet.com/outline HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 6666
Date: Mon, 02 Aug 2010 13:25:28 GMT
Content-Type: application/pdf

%PDF-1.4
1 0 obj
<< /Length 2 0 R
/Filter /FlateDecode
>>
stream
...

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
The aboutstr argument was not valid UTF-8. 400 (Bad Request)
No object with the given about value exists. 404 (Not Found)
If the object has no instance of the tag, or if the tag or a parent namespace does not exist. 404 (Not Found)
If the user does not have READ permission on the tag. 401 (Unauthorized)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
If you do not specify an Accept header value that allows the tag value to be returned. 406 (Not Acceptable)
If the object has an instance of the tag and the requesting user has READ permission for the tag. 200 (OK)

HEAD

|top

The HEAD method on about can be used to test whether an object has a given tag or not, without retrieving the value of the tag.

HEAD /about/aboutstr/namespace1/namespace2/tag

Test for the existence of a tag on the object (if any) whose fluiddb/about is aboutstr.

Example

Retrieve information about a tag attached to a specific object.

Request

HEAD /about/Barcelona/ntoll/review HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 31288
Date: Mon, 02 Aug 2010 13:26:25 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
The aboutstr argument was not valid UTF-8. 400 (Bad Request)
No object with the given about value exists. 404 (Not Found)
If the object has no instance of the tag, or if the tag or a parent namespace does not exist. 404 (Not Found)
If the user does not have READ permission on the tag. 401 (Unauthorized)
The object has an instance of the tag. 200 (OK)

PUT

|top

Create or update a tag on an object.

PUT /about/aboutstr/namespace1/namespace2/tag

Create or update a tag on the object whose fluiddb/about is aboutstr. If no object with fluiddb/about = aboutstr exists, it will be created. The tag value is sent in the payload of the request. See here for more details.

Example

Write a primitive value (in this case 'true') to the Fluidinfo object whose fluiddb/about value is 台北 (Taipei). 台北 are the two unicode codepoints U+53F0 and U+5317, each of which is a 3-byte sequence in UTF-8 (0xE5 0x8F 0xB0 and 0xE5 0x8C 0x97 respectively). Note the Content-Type header in the request is set to application/vnd.fluiddb.value+json to indicate to Fluidinfo that this is a primitive value.

Request

PUT /about/%E5%8F%B0%E5%8C%97/ntoll/cities/visited HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/vnd.fluiddb.value+json

true

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 14:31:47 GMT
Content-Type: text/html

Example

Write an opaque value type to Fluidinfo. Note that the Content-Type header in the request is set to application/pdf indicating to Fluidinfo that this value is opaque. When this value is retrieved the Content-Type header in the response will be application/pdf. (The body of the request has been truncated.)

Request

PUT /about/Barcelona/lonelyplanet.com/outline HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/pdf

%PDF-1.4
1 0 obj
<< /Length 2 0 R
/Filter /FlateDecode
>>
stream
...

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 14:33:40 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
The aboutstr argument was not valid UTF-8. 400 (Bad Request)
If the user does not have CREATE permission on the tag. 401 (Unauthorized)
An error with the request payload. More details. 400 (Bad Request)
If the tag is successfully created / updated on the object. 204 (No Content)

DELETE

|top

Delete a tag from an object. Note that it is not possible to delete a Fluidinfo object.

DELETE /about/aboutstr/namespace1/namespace2/tag

Delete a tag from an object.

Example

Delete the ntoll/rating tag from the object about Barcelona.

Request

DELETE /about/Barcelona/ntoll/rating HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 14:56:52 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If an intermediate namespace does not exist. 404 (Not Found)
If the tag does not exist. 404 (Not Found)
The aboutstr argument was not valid UTF-8. 400 (Bad Request)
No object with the given about value exists. 404 (Not Found)
If the user does not have DELETE permission on the tag. 401 (Unauthorized)
The tag is successfully deleted from the object. 204 (No Content)

Namespaces

POST

|top
POST /namespaces/namespace1/namespace2

Create a new namespace. Intermediate namespaces are created automatically if they don't already exist.

Request payload

The request payload must be sent in application/json format with the following fields:

Field name Field type Mandatory Description
description unicode string True A description of the namespace.
name unicode string True The name of the new namespace.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
URI unicode string The URI of the new namespace.
id unicode string The id of the object that corresponds to the new namespace.

Example

Create a new namespace called 'people' in the test user's top-level namespace.

Request

POST /namespaces/test HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/json

{
 "description": "A namespace for tags that I'm using to add to people",
 "name": "people"
}

Response

HTTP/1.1 201 Created
Content-Length: 110
Location: http://fluiddb.fluidinfo.com/namespaces/test/people
Date: Mon, 02 Aug 2010 12:40:41 GMT
Content-Type: application/json

{"id": "e9c97fa8-05ed-4905-9f72-8d00b7390f9b",
 "URI": "http://fluiddb.fluidinfo.com/namespaces/test/people"}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the namespace already exists. 412 (Precondition Failed)
If a parent namespace does not exist and you do not have permission to create it. 404 (Not Found)
If the requesting user does not have CREATE permission on the parent namespace. 401 (Unauthorized)
If the full path of the new namespace is too long. The current maximum path length is 233 characters. 400 (Bad Request)
An error with the request payload. More details. 400 (Bad Request)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
If the namespace is created successfully. 201 (Created)

Note:

  1. The new namespace will have permissions set according to the user's defaults. There is no permission inheritance in Fluidinfo.

GET

|top
GET /namespaces/namespace1/namespace2

Get information about the namespaces contained in a namespace.

URI arguments:

Name Type Default Mandatory Description
returnDescription Boolean False False If True, also return the namespace description.
returnNamespaces Boolean False False If True, also return the names of the namespaces in this namespace.
returnTags Boolean False False If True, also return the names of the tags in this namespace.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
description unicode string A description of the namespace. This field is only present if returnDescription is True in the request.
id unicode string The id of the Fluidinfo object corresponding to the namespace.
namespaceNames list of unicode strings The names of the sub-namespaces in this namespace. This field is only present if returnNamespaces is True in the request.
tagNames list of unicode strings The names of the tags in this namespace (only present if returnTags is True in the request).

Example

Retrieve information about the test/people namespace.

Request

GET /namespaces/test/people?returnDescription=True&returnNamespaces=True&returnTags=True HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 118
Date: Mon, 02 Aug 2010 12:43:05 GMT
Content-Type: application/json

{"tagNames": [], "namespaceNames": [], "id": "e9c97fa8-05ed-4905-9f72-8d00b7390f9b",
"description": "A namespace for tags I'm using to add to people"}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the namespace does not exist. 404 (Not Found)
If an intermediate namespace does not exist. 404 (Not Found)
If the requesting user does not have LIST permission on the namespace. 401 (Unauthorized)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
No error. 200 (OK)

PUT

|top
PUT /namespaces/namespace1/namespace2

Update a namespace.

Request payload

The request payload must be sent in application/json format with the following fields:

Field name Field type Mandatory Description
description unicode string True A description of the namespace.

Example

Update the description of the test/people namespace.

Request

PUT /namespaces/test/people HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/json

{
  "description": "Contains tags used to annotate objects representing people"
}

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 12:46:38 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the namespace does not exist. 404 (Not Found)
If an intermediate namespace does not exist. 404 (Not Found)
If the requesting user does not have UPDATE permission on the namespace. 401 (Unauthorized)
An error with the request payload. More details. 400 (Bad Request)
If the namespace is updated successfully. 204 (No Content)

DELETE

|top
DELETE /namespaces/namespace1/namespace2

Delete a namespace.

Example

Delete the test/people namespace.

Request

DELETE /namespaces/test/people HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 12:47:25 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the namespace does not exist. 404 (Not Found)
If an intermediate namespace does not exist. 404 (Not Found)
If the requesting user does not have DELETE permission on the namespace. 401 (Unauthorized)
If the namespace is not empty. A namespace is empty if it contains no other namespaces or tags. 412 (Precondition Failed)
If the namespace is deleted successfully. 204 (No Content)

Note:

  1. A namespace can only be deleted if it is empty. I.e., it must not contain any sub-namespaces or any tags.

Objects

POST

|top

Create a new Fluidinfo object.

POST /objects

Create a new object. You must provide credentials for this call to succeed.

Request payload

The request payload must be sent in application/json format with the following fields:

Field name Field type Mandatory Description
about unicode string False The value for the about tag. If you do not want an an about tag on this object, omit this field.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
URI unicode string The URI of the new object.
id unicode string The id of the new object.

Example

Create an object with an about tag that indicates the object represents the book 'Dune'.

Request

POST /objects HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/json

{
  "about": "book:Dune"
}

Response

HTTP/1.1 201 Created
Content-Length: 134
Location: http://fluiddb.fluidinfo.com/objects/9c8e4b12-4b7d-40d2-865b-d5b1945350b1
Date: Mon, 02 Aug 2010 13:00:29 GMT
Content-Type: application/json

{"id": "9c8e4b12-4b7d-40d2-865b-d5b1945350b1",
"URI": "http://fluiddb.fluidinfo.com/objects/9c8e4b12-4b7d-40d2-865b-d5b1945350b1"}

Example

Create a new object without an about tag.

Request

POST /objects HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/json

Response

HTTP/1.1 201 Created
Content-Length: 134
Location: http://fluiddb.fluidinfo.com/objects/741fdbcb-a8c5-449f-a3cf-50c89ee63cdb
Date: Mon, 02 Aug 2010 13:01:05 GMT
Content-Type: application/json

{"id": "741fdbcb-a8c5-449f-a3cf-50c89ee63cdb",
"URI": "http://fluiddb.fluidinfo.com/objects/741fdbcb-a8c5-449f-a3cf-50c89ee63cdb"}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
An error with the request payload. More details. 400 (Bad Request)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
If valid credentials are not provided. 401 (Unauthorized)
A new object was created without error. 201 (Created)

Notes:

  1. The response will also contain a Location header giving the URI for the new object.
  2. If you pass an about value and there is already a Fluidinfo object whose about tag has that value, the returned object id will be that of the pre-existing object.

GET

|top

The GET method on objects is used to retrieve objects matching a query (on object tags), to retrieve information about a particular object, or to retrieve the value of a tag on a particular object.

GET /objects

Search for objects that match a query.

URI arguments:

Name Type Default Mandatory Description
query string   True A query string specifying what sorts of objects to return. The query language is described here. You must convert your query to UTF-8 and then percent-encode it before adding it to the request URI

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
ids list of unicode strings A list of object ids matching the query. Each object id is a UUID string (as described here).

Example

Search for objects in Fluidinfo (note the URL encoded query argument).

Request

GET /objects?query=has%20ntoll/met%20and%20has%20terrycojones/met HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 209
Date: Mon, 02 Aug 2010 13:14:32 GMT
Content-Type: application/json

{"ids": ["5a4823a4-26b4-495c-9a29-a1e830a1b153", "8b07a7ec-e5f7-46cd-9cd1-9a40c3137762",
"83f2ad81-43db-421a-adc4-974f3a8bca0d", "ac1e937e-dd76-426e-a2b5-06a439a708cc",
"52bc041d-e8f4-4f8d-a66a-a3b5ea5fa156"]}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If no query is given. 400 (Bad Request)
The query string was not valid UTF-8. 400 (Bad Request)
If the query string could not be parsed. 400 (Bad Request)
If one or more of the tags or namespaces present in the query do not exist. 404 (Not Found)
If the query (or any of its sub-parts) results in too many matching objects. The current limit is 1 million objects. 413 (Request Entity Too Large)
If the user does not have READ permission on a tag whose value is needed to satisfy the query. 401 (Unauthorized)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
No error occurred. 200 (OK)
GET /objects/id

To request information on a particular object, include the object ID in the request URI. The return information will indicate which tags are present on the object, though not with the tag values.

URI arguments:

Name Type Default Mandatory Description
showAbout string False False If True, return the value of the about tag on the object. If the object does not have an about tag, the response payload will still contain an about key, with, in the case of a JSON payload, a null value. If False, the payload will not have an about key.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
about unicode string The about tag on the object, if any.
tagPaths list of unicode strings The full path names of the tags on this object (for which the user has READ permission), if any.

Example

Retrieve information about a specific object (the 'tagPaths' list in the response has been truncated)

Request

GET /objects/5a4823a4-26b4-495c-9a29-a1e830a1b153?showAbout=True HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 1080
Date: Mon, 02 Aug 2010 13:16:09 GMT
Content-Type: application/json

{"about": "twitter.com:uid:5893972", "tagPaths": ["twitter.com/friends/fxn"]}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the given ID is not a valid UUID. 404 (Not Found)
An error with the request payload. More details. 400 (Bad Request)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
No error occurred. 200 (OK)

Note:

  1. An object ID has the form of a UUID, as described here.
GET /objects/id/namespace1/namespace2/tag

Retrieve the value of a tag from an object. The value is returned in the payload of the response. If the requested value is a primitive, an X-FluidDB-Type header will be added to the response indicating the type of the value. Please see here for more details.

Example

Return a primitive value type from Fluidinfo. Note that the Content-Type header in the response is application/vnd.fluiddb.value+json, as given to Fluidinfo when the value was PUT.

Request

GET /objects/5a4823a4-26b4-495c-9a29-a1e830a1b153/twitter.com/users/screen_name HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 6
Date: Mon, 02 Aug 2010 13:20:31 GMT
Content-Type: application/vnd.fluiddb.value+json
X-FluidDB-Type: string

"HD42"

Example

Return an opaque value type from Fluidinfo. Note that the Content-Type header in the response is text/html, because the tag value is of that type, as given to Fluidinfo when the value was PUT.

Request

GET /objects/366375a5-c811-4c59-a469-0a3efb602411/ntoll/fluidapp/tweetmeet/index.html HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 6666
Date: Mon, 02 Aug 2010 13:25:28 GMT
Content-Type: text/html

<html>
   <head>
          <title>Hello</title>
   </head>
   <body>
       Hello
   </body>
</html>

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
If the user does not have READ permission for the tag. 401 (Unauthorized)
If the object has no instance of the tag, or if the tag or a parent namespace does not exist. 404 (Not Found)
If you do not specify an Accept header value that allows the tag value to be returned. 406 (Not Acceptable)
If the object has an instance of the tag. 200 (OK)

HEAD

|top

The HEAD method on objects can be used to test whether an object has a given tag or not, without retrieving the value of the tag.

HEAD /objects/id/namespace1/namespace2/tag

Test for the existence of a tag on an object. If the requested tag has a primitive value, an X-FluidDB-Type header will be added to the response indicating the type of the value. Please see here for more details.

Example

Retrieve the headers associated with a tag attached to a specific object.

Request

HEAD /objects/366375a5-c811-4c59-a469-0a3efb602411/ntoll/fluidapp/tweetmeet/index.html HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 28926
Date: Mon, 02 Aug 2010 13:26:25 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the user does not have READ permission for the tag. 401 (Unauthorized)
If the object has no instance of the tag, or if the tag or a parent namespace does not exist. 404 (Not Found)
The object has an instance of the tag. 200 (OK)

PUT

|top

Create or update a tag on an object. Unknown namespaces and tags are created automatically.

PUT /objects/id/namespace1/namespace2/tag

Create or update a tag on an object. The tag value is sent in the payload of the request. See here for more details.

Example

Write a primitive value type to Fluidinfo. Note the Content-Type header in the request is set to application/vnd.fluiddb.value+json to indicate to Fluidinfo that this is a primitive value.

Request

PUT /objects/5a4823a4-26b4-495c-9a29-a1e830a1b153/test/quz HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/vnd.fluiddb.value+json

"1.234"

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 14:31:47 GMT
Content-Type: text/html

Example

Write an opaque value type to Fluidinfo. Note that the Content-Type header in the request is set to application/pdf indicating to Fluidinfo that this value is opaque. When this value is retrieved the Content-Type header in the response will be application/pdf. (Note: the body of the request has been truncated.)

Request

PUT /objects/5a4823a4-26b4-495c-9a29-a1e830a1b153/test/quz HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/pdf

%PDF-1.4
1 0 obj
<< /Length 2 0 R
/Filter /FlateDecode
>>
stream
...

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 14:33:40 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the user does not have CREATE permission on the tag. 401 (Unauthorized)
An error with the request payload. More details. 400 (Bad Request)
If the tag is successfully created / updated on the object. 204 (No Content)

DELETE

|top

Delete a tag from an object. Note that it is not possible to delete a Fluidinfo object.

DELETE /objects/id/namespace1/namespace2/tag

Delete a tag from an object.

Example

Delete the test/quz tag from the referenced object.

Request

DELETE /objects/5a4823a4-26b4-495c-9a29-a1e830a1b153/test/quz HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 14:56:52 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the object id is malformed. 404 (Not Found)
If an intermediate namespace does not exist. 404 (Not Found)
If the tag does not exist. 404 (Not Found)
If the user does not have DELETE permission on the tag. 401 (Unauthorized)
The tag is successfully deleted from the object. 204 (No Content)

Note:

  1. You will receive a 204 (No Content) status even if the object has no instance of the tag.

Permissions

POST

|top

POST is not supported on permissions, because permissions are automatically set from a user's default permissions when a namespace or tag is first created. Use PUT to adjust the permissions on a given namespace or tag.

GET

|top
GET /permissions/namespaces/namespace1/namespace2

Get the permissions on a namespace: the open/closed policy, and the set of exceptions to the policy.

URI arguments:

Name Type Default Mandatory Description
action string   True The action whose permissions information is sought. Possible values are: create, update, delete, list, control.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
exceptions list of unicode strings The names of the users who are exceptions to the policy.
policy unicode string The policy (either 'open' or 'closed').

Example

Retrieve the 'create' policy for the test namespace.

Request

GET /permissions/namespaces/test?action=create HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 44
Date: Mon, 02 Aug 2010 14:58:28 GMT
Content-Type: application/json

{"policy": "closed", "exceptions": ["test"]}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If an intermediate namespace does not exist. 404 (Not Found)
If the namespace does not exist. 404 (Not Found)
If the requesting user does not have CONTROL permission on the namespace. 401 (Unauthorized)
If the action argument is missing or invalid. 400 (Bad Request)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
No error. 200 (OK)
GET /permissions/tags/namespace1/namespace2/tag

Get the permissions on a tag: the open/closed policy, and the set of exceptions to the policy.

URI arguments:

Name Type Default Mandatory Description
action string   True The action whose permissions information is sought. Possible values are: update, delete, control.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
exceptions list of unicode strings The names of the users who are exceptions to the policy.
policy unicode string The policy (either 'open' or 'closed').

Example

Retrieve the 'update' policy for the test/quz tag.

Request

GET /permissions/tags/test/quz?action=update HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 44
Date: Mon, 02 Aug 2010 14:59:22 GMT
Content-Type: application/json

{"policy": "closed", "exceptions": ["test"]}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If an intermediate namespace does not exist. 404 (Not Found)
If the tag does not exist. 404 (Not Found)
If the requesting user does not have CONTROL permission on the tag. 401 (Unauthorized)
If the action argument is missing or invalid. 400 (Bad Request)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
No error. 200 (OK)
GET /permissions/tag-values/namespace1/namespace2/tag

Get the permissions on the set of tag instances: the open/closed policy, and the set of exceptions to the policy.

URI arguments:

Name Type Default Mandatory Description
action string   True The action whose permissions information is sought. Possible values are: write, read, delete, control.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
exceptions list of unicode strings The names of the users who are exceptions to the policy.
policy unicode string The policy (either 'open' or 'closed').

Example

Retrieve the 'delete' policy for values associated with the test/quz tag.

Request

GET /permissions/tag-values/test/quz?action=delete HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 36
Date: Mon, 02 Aug 2010 14:59:54 GMT
Content-Type: application/json

{"policy": "open", "exceptions": []}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If an intermediate namespace does not exist. 404 (Not Found)
If the tag does not exist. 404 (Not Found)
If the requesting user does not have CONTROL permission on the tag. 401 (Unauthorized)
If the action argument is missing or invalid. 400 (Bad Request)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
No error. 200 (OK)

PUT

|top
PUT /permissions/namespaces/namespace1/namespace2

Update the permissions on a namespace: the open/closed policy, and the set of exceptions to the policy.

URI arguments:

Name Type Default Mandatory Description
action string   True The action whose permissions information is to be updated. Possible values are: create, update, delete, list, control.

Request payload

The request payload must be sent in application/json format with the following fields:

Field name Field type Mandatory Description
exceptions list of unicode strings True The names of the users who are exceptions to the policy.
policy unicode string True The policy (either 'open' or 'closed').

Example

Update the 'create' policy for the test namespace.

Request

PUT /permissions/namespaces/test?action=create HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/json

{
  "policy": "closed",
  "exceptions": ["test", "ntoll"]
}

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 15:03:42 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If an intermediate namespace does not exist. 404 (Not Found)
If the namespace does not exist. 404 (Not Found)
If the requesting user does not have CONTROL permission on the namespace. 401 (Unauthorized)
The user named in the exceptions list does not exist. 412 (Precondition Failed)
If the policy is not 'open' or 'closed'. 400 (Bad Request)
If the action argument is missing or invalid. 400 (Bad Request)
If an invalid user is specified in the exceptions list. 400 (Bad Request)
If a user in the exceptions list does not exist. 404 (Not Found)
An error with the request payload. More details. 400 (Bad Request)
If permissions are changed successfully. 204 (No Content)
PUT /permissions/tags/namespace1/namespace2/tag

Update the permissions on a tag: the open/closed policy, and the set of exceptions to the policy.

URI arguments:

Name Type Default Mandatory Description
action string   True The action whose permissions information is to be updated. Possible values are: update, delete, control.

Request payload

The request payload must be sent in application/json format with the following fields:

Field name Field type Mandatory Description
exceptions list of unicode strings True The names of the users who are exceptions to the policy.
policy unicode string True The policy (either 'open' or 'closed').

Example

Update the 'update' policy for the test/quz tag.

Request

PUT /permissions/tags/test/quz?action=update HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/json

{
  "policy": "closed",
  "exceptions": ["test", "ntoll"]
}

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 15:04:39 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If an intermediate namespace does not exist. 404 (Not Found)
If the tag does not exist. 404 (Not Found)
If the requesting user does not have CONTROL permission on the tag. 401 (Unauthorized)
The user named in the exceptions list does not exist. 412 (Precondition Failed)
If the policy is not 'open' or 'closed'. 400 (Bad Request)
If the action argument is missing or invalid. 400 (Bad Request)
An error with the request payload. More details. 400 (Bad Request)
If permissions are changed successfully. 204 (No Content)
PUT /permissions/tag-values/namespace1/namespace2/tag

Update the permissions on a tag's instances: the open/closed policy, and the set of exceptions to the policy.

URI arguments:

Name Type Default Mandatory Description
action string   True The action whose permissions information is to be updated. Possible values are: write, read, delete, control.

Request payload

The request payload must be sent in application/json format with the following fields:

Field name Field type Mandatory Description
exceptions list of unicode strings True The names of the users who are exceptions to the policy.
policy unicode string True The policy (either 'open' or 'closed').

Example

Update the 'write' policy for values associated with the test/quz tag.

Request

PUT /permissions/tag-values/test/quz?action=write HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/json

{
  "policy": "closed",
  "exceptions": ["test", "ntoll"]
}

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 15:08:44 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If an intermediate namespace does not exist. 404 (Not Found)
If the tag does not exist. 404 (Not Found)
If the requesting user does not have CONTROL permission on the tag. 401 (Unauthorized)
The user named in the exceptions list does not exist. 412 (Precondition Failed)
If the policy is not 'open' or 'closed'. 400 (Bad Request)
If the action argument is missing or invalid. 400 (Bad Request)
An error with the request payload. More details. 400 (Bad Request)
If permissions are changed successfully. 204 (No Content)

DELETE

|top

DELETE is not supported on permissions because namespaces and tags must always have a set of permissions.

Recent

GET

|top

The GET method on recent is used to retrieve information about the latest updated tag values on a given object or user.

GET /recent/objects

To request information on the latest tag values on the objects returned by a given query

URI arguments:

Name Type Default Mandatory Description
query string   True A query string specifying what sorts of objects to get recent activity for. The query language is described here. You must convert your query to UTF-8 and then percent-encode it before adding it to the request URI

Example

Retrieve information about recent values on objects followed by bob.

Request

GET /recent/objects?query=has+bob%2Ffollows HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 1027
Date: Mon, 02 Aug 2010 13:16:09 GMT
Content-Type: application/json

[ { "about" : "http://en.wikipedia.org/wiki/Billion_laughs",
    "id" : "63a5413d-2e0f-4078-9c04-00e58a727478",
    "tag" : "bob/like",
    "updated-at" : "2012-02-22T19:21:50.208654",
    "username" : "bob",
    "value" : null
  },
  { "about" : "shake shack",
    "id" : "91ec45ca-31b3-4c26-b480-27985f1ed902",
    "tag" : "terrycojones/image",
    "updated-at" : "2012-02-22T04:18:38.093100",
    "username" : "terrycojones",
    "value" : "http://imgur.com/gallery/c2JdZ"
  },
  { "about" : "https://twitter.com/#!/terrycojones/status/1721...",
    "id" : "f054aa74-21f4-404d-9540-e7de4afda035",
    "tag" : "mike/comment",
    "updated-at" : "2012-02-22T04:03:31.850967",
    "username" : "mike",
    "value" : "I had to annotate my own tweet about annotating tweets."
  },
 { "about" : "http://www.sublimetext.com/",
    "id" : "362f95bd-5429-4a3d-90f7-576860ea7bac",
    "tag" : "ceronman/comment",
    "updated-at" : "2012-02-22T15:00:16.957497",
    "username" : "ceronman",
    "value" : "Very cool text editor."
  }]

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If no query is given. 400 (Bad Request)
The query string was not valid UTF-8. 400 (Bad Request)
If the query string could not be parsed. 400 (Bad Request)
If the query returns to many objects. 400 (Bad Request)
If one or more of the tags or namespaces present in the query do not exist. 404 (Not Found)
If the user does not have READ permission on a tag whose value is needed to satisfy the query. 401 (Unauthorized)
No error. 200 (OK)
GET /recent/objects/id

To request information on the latest tag values on a particular object given its objectID

Example

Retrieve information about recent tag values for the object 5a4823a4-26b4-495c-9a29-a1e830a1b153.

Request

GET /recent/objects/5a4823a4-26b4-495c-9a29-a1e830a1b153 HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 494
Date: Mon, 02 Aug 2010 13:16:09 GMT
Content-Type: application/json

[ { "about" : "Birds",
    "id" : "5a4823a4-26b4-495c-9a29-a1e830a1b153",
    "tag" : "bob/test",
    "updated-at" : "2012-02-13T17:22:58.389364",
    "username" : "bob",
    "value" : [ "One", "Two", "Three" ]
  },
  { "about" : "Birds",
    "id" : "5a4823a4-26b4-495c-9a29-a1e830a1b153",
    "tag" : "fred/test_ogg",
    "updated-at" : "2012-01-03T23:44:28.463887",
    "username" : "fred",
    "value" : {
        "value-type" : "audio/ogg",
        "size" : 239367
      }
  } ]

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the id is not a valid UUID. 400 (Bad Request)
No error. 200 (OK)
GET /recent/about/aboutstr

To request information on the latest tag values on a particular object given its fluiddb/about value

Example

Retrieve information about recent tag values on the object "Birds".

Request

GET /recent/about/Birds HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 703
Date: Mon, 02 Aug 2010 13:16:09 GMT
Content-Type: application/json

[ { "about" : "Birds",
    "id" : "5a4823a4-26b4-495c-9a29-a1e830a1b153",
    "tag" : "bob/test",
    "updated-at" : "2012-02-13T17:22:58.389364",
    "username" : "bob",
    "value" : [ "One", "Two", "Three" ]
  },
  { "about" : "Birds",
    "id" : "5a4823a4-26b4-495c-9a29-a1e830a1b153",
    "tag" : "fred/film",
    "updated-at" : "2011-12-02T04:21:02.588383",
    "username" : "fred",
    "value" : "The Birds by Alfred Hitchcock"
  } ]

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
No error. 200 (OK)
GET /recent/users

To request information on the latest tag values by the users whose objects are returned by a given query

URI arguments:

Name Type Default Mandatory Description
query string   True A query string specifying what sorts of user objects to get recent activity for. The query language is described here. You must convert your query to UTF-8 and then percent-encode it before adding it to the request URI

Example

Retrieve information about recent values by users followed by bob.

Request

GET /recent/object?query=has+bob%2Ffollows HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 1027
Date: Mon, 02 Aug 2010 13:16:09 GMT
Content-Type: application/json

[ { "about" : "http://en.wikipedia.org/wiki/Billion_laughs",
    "id" : "63a5413d-2e0f-4078-9c04-00e58a727478",
    "tag" : "bob/like",
    "updated-at" : "2012-02-22T19:21:50.208654",
    "username" : "bob",
    "value" : null
  },
  { "about" : "shake shack",
    "id" : "91ec45ca-31b3-4c26-b480-27985f1ed902",
    "tag" : "terrycojones/image",
    "updated-at" : "2012-02-22T04:18:38.093100",
    "username" : "terrycojones",
    "value" : "http://imgur.com/gallery/c2JdZ"
  },
  { "about" : "https://twitter.com/#!/terrycojones/status/1721...",
    "id" : "f054aa74-21f4-404d-9540-e7de4afda035",
    "tag" : "mike/comment",
    "updated-at" : "2012-02-22T04:03:31.850967",
    "username" : "mike",
    "value" : "I had to annotate my own tweet about annotating tweets."
  },
 { "about" : "http://www.sublimetext.com/",
    "id" : "362f95bd-5429-4a3d-90f7-576860ea7bac",
    "tag" : "ceronman/comment",
    "updated-at" : "2012-02-22T15:00:16.957497",
    "username" : "ceronman",
    "value" : "Very cool text editor."
  }]

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If no query is given. 400 (Bad Request)
The query string was not valid UTF-8. 400 (Bad Request)
If the query string could not be parsed. 400 (Bad Request)
If the query returns to many objects. 400 (Bad Request)
If one or more of the tags or namespaces present in the query do not exist. 404 (Not Found)
If the user does not have READ permission on a tag whose value is needed to satisfy the query. 401 (Unauthorized)
No error. 200 (OK)
GET /recent/users/username

To request information on the latest tag values created or updated by a given user.

Example

Retrieve information about recent tag values created by bob.

Request

GET /recent/users/bob HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 520
Date: Mon, 02 Aug 2010 13:16:09 GMT
Content-Type: application/json

[ { "about" : "american pie",
    "id" : "f6ee212b-c46a-4de6-988f-5a42b89c1e6f",
    "tag" : "bob/rating",
    "updated-at" : "2012-02-14T06:51:13.557860",
    "username" : "bob",
    "value" : 4
  },
  { "about" : "american pie",
    "id" : "f6ee212b-c46a-4de6-988f-5a42b89c1e6f",
    "tag" : "bob/favorite-scene",
    "updated-at" : "2012-02-14T06:50:55.703272",
    "username" : "bob",
    "value" : "http://www.youtube.com/watch?v=Zf_iE5D8nIQ"
  },
  { "about" : "the cake store",
    "id" : "435ba13a-255b-4baf-9609-6caaed72f049",
    "tag" : "bob/lat-long",
    "updated-at" : "2012-02-14T06:44:14.621746",
    "username" : "bob",
    "value" : [ "51.436889", "-0.049438" ]
  } ]

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the user does not exist. 404 (Not Found)
No error. 200 (OK)

Tags

POST

|top
POST /tags/namespace1/namespace2

Add a tag name to a namespace. Intermediate namespaces are created automatically if they don't already exist.

Request payload

The request payload must be sent in application/json format with the following fields:

Field name Field type Mandatory Description
description unicode string True A description of the tag.
indexed boolean True Whether or not tag values should be indexed.
name unicode string True The name of the new tag.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
URI unicode string The URI of the new object.
id unicode string The id of the object that corresponds to the new tag.

Example

Create a new tag called 'rating' in the test users top-level namespace.

Request

POST /tags/test HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/json

{
  "description": "How I rate things on a scale of 1 (worst) to 10 (best).",
  "indexed": false,
  "name": "rating"
}

Response

HTTP/1.1 201 Created
Content-Length: 110
Location: http://fluiddb.fluidinfo.com/tags/test/rating
Date: Mon, 02 Aug 2010 15:15:00 GMT
Content-Type: application/json

{"id": "56e0c31a-1a4c-4091-8a65-b37af769752a",
"URI": "http://fluiddb.fluidinfo.com/tags/test/rating"}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the containing namespace or an intermediate namespace does not exist and you do not have permission to create it. 404 (Not Found)
If the user does not have CREATE permission on the containing (i.e., deepest) namespace. 401 (Unauthorized)
If the tag already exists. 412 (Precondition Failed)
If the full path of the new tag is too long. The current maximum path length is 233 characters. 400 (Bad Request)
An error with the request payload. More details. 400 (Bad Request)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
If the tag is created successfully. 201 (Created)

Notes:

  1. A Location header will be returned containing the URI of the new tag.
  2. This method creates a tag itself, not the value of a tag on a particular object (for that, use POST on /objects/id/namespace1/namespace2/tag).

GET

|top
GET /tags/namespace1/namespace2/tag

Retrieve information about the tag.

URI arguments:

Name Type Default Mandatory Description
returnDescription Boolean False False If True, return the description of the tag.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
description unicode string A description of the tag. This field is only present if returnDescription is True in the request.
id unicode string The id of the Fluidinfo object corresponding to the tag.
indexed boolean Whether or not tag values are indexed.

Example

Retrieve information about the test/rating tag.

Request

GET /tags/test/rating?returnDescription=True HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 108
Date: Mon, 02 Aug 2010 15:15:59 GMT
Content-Type: application/json

{"indexed": false, "id": "56e0c31a-1a4c-4091-8a65-b37af769752a",
"description": "How I rate things on a scale of 1 (worst) to 10 (best)."}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If an intermediate namespace does not exist. 404 (Not Found)
If the tag does not exist. 404 (Not Found)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
No error. 200 (OK)

Note:

  1. This method retrieves information about the tag itself, not the value of a tag on an object (to get the value on an object, use GET on /objects/id/namespace1/namespace2/tag).

PUT

|top
PUT /tags/namespace1/namespace2/tag

Update information about a tag in a namespace.

Request payload

The request payload must be sent in application/json format with the following fields:

Field name Field type Mandatory Description
description unicode string True A description of the tag.

Example

Update the description of the test/rating tag.

Request

PUT /tags/test/rating HTTP/1.1
Authorization: Basic XXXXXXXX
Content-Length: XXXXXXXX
Content-Type: application/json

{
  "description": "Indicates rating from 1 (bad) -> 10 (good)"
}

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 15:16:59 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If an intermediate namespace does not exist. 404 (Not Found)
If the tag does not exist. 404 (Not Found)
If the requesting user does not have UPDATE permission on the tag. 401 (Unauthorized)
An error with the request payload. More details. 400 (Bad Request)
If the operation completes successfully. 204 (No Content)

Note:

  1. Changing whether a tag is indexed after it has been created is not currently supported.

DELETE

|top
DELETE /tags/namespace1/namespace2/tag

Delete a tag. The tag name is removed from its containing namespace and all occurences of the tag on objects are deleted.

Example

Delete the test/rating tag.

Request

DELETE /tags/test/rating HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 204 No Content
Date: Mon, 02 Aug 2010 15:17:38 GMT
Content-Type: text/html

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If an intermediate namespace does not exist. 404 (Not Found)
If the tag does not exist. 404 (Not Found)
If the requesting user does not have DELETE permission on the tag. 401 (Unauthorized)
If the operation completes successfully. 204 (No Content)

Users

GET

|top
GET /users/username

Return information about a particular user.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
id unicode string The id of the object corresponding to the user.
name unicode string The user's name.

Example

Retrieve information about the user 'ntoλλ'. Note that to specify unicode 'λ' characters in the request URI, you must first convert them to UTF-8 and then URL-encode them. Unicode is returned in the response, in the manner specified by the JSON specification.

Request

GET /users/nto%CE%BB%CE%BB HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Length: 62
Date: Mon, 02 Aug 2010 15:18:17 GMT
Content-Type: application/json

{"name": "Nicholas To\u03bb\u03bbervey",
 "id": "42909deb-9854-47ae-a8f8-3f59d4fbe5a5"}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the user does not exist. 404 (Not Found)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
No error. 200 (OK)

Values

GET

|top

The GET method on values is used to retrieve tag values from objects matching a query.

GET /values

Search for objects matching a Fluidinfo query, and return the value of the requested tags on the matching objects.

URI arguments:

Name Type Default Mandatory Description
query string   True A query string specifying what objects to match. The Fluidinfo query language is described here.
tag string   True The name of a tag whose value should be returned. Repeat this argument as many times as needed. All values are returned if '*' is specified.

Response payload

The response payload will be sent in application/json format with the following fields:

Field name Field type Description
results dictionary A dictionary containing information about the requested tag values on objects that match the query. See example below.

Example

Search for objects in Fluidinfo matching mike/rating > 5 and retrieve values for the tags ntoll/rating, ntoll/resume, fluiddb/about, and bit.ly/url from those objects.

Request

GET /values?query=mike%2Frating>5&tag=ntoll/rating&tag=ntoll/resume&tag=fluiddb/about&tag=bit.ly/url HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 200 OK
Content-Length: 817
Date: Mon, 02 Aug 2010 13:14:32 GMT
Content-Type: application/json

{
    "results" : {
        "id" : {
            "05eee31e-fbd1-43cc-9500-0469707a9bc3" : {
                "fluiddb/about" : {
                    "value" : "Hey you",
                    "updated-at" : "2012-02-13T18:15:24.571150"
                },
                "ntoll/rating" : {
                    "value" : 5,
                    "updated-at" : "2012-02-13T18:16:57.942384"
                },
                "ntoll/resume" : {
                    "value-type" : "application/pdf",
                    "size" : 179393,
                    "updated-at" : "2012-02-13T18:15:24.571150"
                }
            },
            "0521e31e-fbd1-43cc-9500-046974569bc3" : {
                "fluiddb/about" : {
                    "value" : "http://www.yahoo.com",
                    "updated-at" : "2012-02-13T18:15:24.571150",
                },
                "ntoll/rating" : {
                    "value" : 9,
                    "updated-at" : "2012-02-13T18:16:57.942384"
                },
                "bit.ly/url" : {
                    "value" : "http://bit.ly/4bYAV2",
                    "updated-at" : "2012-02-13T18:15:24.571150"
                }
            }
        }
    }
}

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If no query or tag is given. 400 (Bad Request)
If the query string could not be parsed. 400 (Bad Request)
If the query (or any of its sub-parts) results in too many matching objects. The current limit is 1 million objects. 413 (Request Entity Too Large)
If the requesting user does not have READ permission on a tag whose value is needed to satisfy the query. 401 (Unauthorized)
If the requesting user does not have READ permission on a tag whose value is requested. 401 (Unauthorized)
An error with the request makes it impossible to respond. More details. 400 (Bad Request)
No error occurred. 200 (OK)

PUT

|top

The PUT method on values sets tag values on objects matching queries. Unknown namespaces and tags are created automatically.

PUT /values

Search for objects matching a series of Fluidinfo queries, and set the values of the given tags on the matching objects.

Example

The following example request will put the given values of ntoll/rating and ntoll/seen onto all objects matching the Fluidinfo query mike/rating > 5, then put the given value of ntoll/rating onto objects matching the query fluiddb/about matches "great", and finally update the mike/seen tag on the object with ID 6ed3e622-a6a6-4a7e-bb18-9d3440678851.

Request

PUT /values HTTP/1.1
Authorization: Basic XXXXXXXX
Content-type: application/json
Content-length: 587

{
    "queries" : [
        [ "mike/rating > 5",
          {
              "ntoll/rating" : {
                  "value" : 6
              },
              "ntoll/seen" : {
                  "value" : true
              }
          }
        ],
        [ "fluiddb/about matches \"great\"",
          {
              "ntoll/rating" : {
                  "value" : 10
              }
          }
        ],
        [ "fluiddb/id = \"6ed3e622-a6a6-4a7e-bb18-9d3440678851\"",
          {
              "mike/seen" : {
                  "value" : true
              }
          }
        ]
    ]
}

Response

HTTP/1.1 204 No Content
Content-Type: text/html
Date: Mon, 02 Aug 2010 13:14:32 GMT

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If the payload specifying queries and tag values cannot be parsed. 400 (Bad Request)
If a query (or any of its sub-parts) results in too many matching objects. The current limit is 1 million objects. 413 (Request Entity Too Large)
If the requesting user does not have READ permission on a tag whose value is needed to satisfy a query. 401 (Unauthorized)
If the requesting user does not have CREATE permission on a tag whose update is requested. 401 (Unauthorized)
If a tag whose update is requested does not exist. 404 (Not Found)
No error occurred. 204 (No Content)

DELETE

|top

The DELETE method on values is used to delete tags from objects matching a query.

DELETE /values

Search for objects matching a Fluidinfo query, and delete the the requested tags from the matching objects.

URI arguments:

Name Type Default Mandatory Description
query string   True A query string specifying what objects to match. The Fluidinfo query language is described here.
tag string   True The name of a tag that should be deleted from objects matching the query. Repeat this argument as many times as needed. All values are returned if '*' is specified.

Example

Search for objects in Fluidinfo matching mike/rating > 5 and delete the tags ntoll/rating and ntoll/resume from those objects.

Request

DELETE /values?query=mike%2Frating>5&tag=ntoll/rating&tag=ntoll/resume HTTP/1.1
Authorization: Basic XXXXXXXX

Response

HTTP/1.1 204 No Content
Content-Type: text/html
Date: Mon, 02 Aug 2010 13:14:32 GMT

HTTP response status codes

The following HTTP response codes may occur:

Condition Return
If no query or tag is given. 400 (Bad Request)
If the query string could not be parsed. 400 (Bad Request)
If the query (or any of its sub-parts) results in too many matching objects. The current limit is 1 million objects. 413 (Request Entity Too Large)
If the requesting user does not have READ permission on a tag whose value is needed to satisfy the query. 401 (Unauthorized)
If the requesting user does not have DELETE permission on a tag whose deletion is requested. 401 (Unauthorized)
If a tag whose deletion is requested does not exist. 404 (Not Found)
No error occurred. 204 (No Content)

Typographic conventions

The following typographic conventions are used above:

  • URIs look like /users/john.
  • When part of a URI is variable, it will look like /users/USERNAME (here USERNAME is variable).
  • The names of namespaces and tags in Fluidinfo look like john/books/rating.
  • Variable parts of namespaces and tags are distinguished as with URIs, e.g., users/USERNAME.
  • Permissions look like CREATE, READ, DELETE, etc.