1. pstatic
  2. webfs

Wiki

Clone wiki

webfs / Docs / metadata

Metadata interface

The metadata interface ("http://p-static.net/webfs/metadata/1.0") allows you to use the GET, PUT, and DELETE HTTP methods to access key-value metadata attached to data objects. (It's similar to extended attributes in a filesystem.) The rest of this page assumes that PATH is the path to a data object, which has been created using the data module, or some equivalent module.

Metadata keys and values must be strings.

Server-provided metadata

The server may generate some metadata fields automatically. This could range from trivial data, like the size of the object or the date that it was created, to more complex data like checksums of the data or the server's guess at the file's MIME type. Servers may use any metadata keys for this data, with the exception of keys that start with the prefix "user_", which are reserved for users.

Servers SHOULD document which keys may be used in the discovery document, in the "server-provided" tag. Servers SHOULD document the meaning of these keys in the discovery document somehow. A future version of the metadata interface may introduce strict definitions for the meanings of the fields, but for now servers should aim to be compatible with what other servers are doing, when possible.

HTTP Methods

GET

A GET returns metadata for an object as JSON. If the query string portion of the URL is provided, then the server returns only the value corresponding to that key; otherwise, all the metadata is returned as a JSON object.

Syntax:

GET http://[webfs path]/[metadata module]/[object path]
GET http://[webfs path]/[metadata module]/[object path]?[key]

HTTP Response codes:

  • 200 OK: The request was successful.
  • 404 Not Found: Either the data object or the metadata key was not found.

PUT

The PUT method is used to create and update metadata. A query string can be provided to write to individual metadata keys, or a full metadata object can be uploaded as a JSON-encoded object.

Syntax:

PUT http://[webfs path]/[metadata module]/[object path]
PUT http://[webfs path]/[metadata module]/[object path]?[key]

HTTP Response codes:

  • 201 Created: When a query string is used, means that the key was successfully created and did not already exist.
  • 204 No Content: The metadata was written successfully.
  • 404 Not Found: The data object specified does not exist.

DELETE

TODO

Examples

# When getting all values, they are returned in a JSON object
> GET http://foo.com/webfs/md/some-object
< {"size": "4542983"}

# When getting just one value, it's returned as a bare string
> GET http://foo.com/webfs/md/some-object?size
< 4542983

# Individual properties can be written to...
> PUT http://foo.com/webfs/md/some-object?foobaz
> this is the value of the key

# ...and they appear in the metadata
> GET http://foo.com/webfs/md/some-object
< {"size": "4542983", "foobaz": "this is the value of the key"}

# Deleting all the metadata for an object
> DELETE http://foo.com/webfs/md/some-object

# Note that server-generated metadata isn't affected by deletion
> GET http://foo.com/webfs/md/some-object
< {"size": "4542983"}

Updated