TOC 
Version 0.9w10n.org
 December 21, 2013


Webification



Table of Contents

1.  Introduction
2.  Abstract Tree View
3.  URL Syntax
    3.1.  Identifier
        3.1.1.  Node
        3.1.2.  Leaf
    3.2.  Query String
4.  HTTP Request
    4.1.  GET Request - Read
    4.2.  PUT Request - Write
5.  HTTP Response
    5.1.  Node
        5.1.1.  Meta
        5.1.2.  Data
    5.2.  Leaf
        5.2.1.  Meta
        5.2.2.  Data
6.  Webification Type
7.  References
Appendix A.  Copyrights
§  Author's Address




 TOC 

1.  Introduction

This open specification defines a common way to expose data stores (composite files, databases, data models, remote services, etc.) on the web platform. The core idea of webification is to make inner components of a data store directly addressable and accessible via well-defined and meaningful URLs.

The word "webification" and its numeronym "w10n" will be used interchangeably in the discussion below.



 TOC 

2.  Abstract Tree View

W10n holds a simple abstract tree view for a data store. In this tree, there are two types of entities (inner components): (1) node, which can contain sub-nodes and leaves. (2) leaf, which can only belong to one parent node and can hold data. Both node and leaf may have attributes. An attribute is not considered as either leaf or node for simplicity. The tree root is a node.

Furthermore a node or leaf must have a name. The name of the tree root is "", namely, an empty string.

The full name of a node or leaf is constructed by concatenating names of all ancestral nodes and its name using forward slash "/" as the separator. Thus the full name of the root is "", an empty string, too. And the full name of a non-root entity x, node or leaf, is

""/x1/x2/.../xn/x

or equivalently

/x1/x2/.../xn/x

in which "", x1, x2, ..., xn are names of its ancestral nodes.

Sometimes, it is useful to combine several nodes and/or leaves into a virtual node. Name of such an entity can be formed by concatenating names of concerned entities using comma inside a pair of curly brackets '{' and '}'. For example, a virtual node constructed from following three nodes or leaves:

/x1/x2/x3/.../xn/x
/y1/y2/y3/.../ym/y
/z1/z2/z3/.../zl/z

will have a fullname as

{/x1/x2/x3.../xn/x,/y1/y2/y3/.../ym/y,/z1/z2/z3/.../zl/z}

In case x1 = y1 = z1 and x2 = y2 = z2, the fullname can be equivalently expressed as

/x1/x2/{x3/.../xn/x,y3/.../ym/y,z3/.../zl/z}

For a node, meta information is available. It contains node name, a list of attributes, a list of sub-nodes and a list of leaves.

For a leaf, both meta and data information are available. The meta information contains leaf name and a list of attributes. The data information can be all or part of data that the leaf holds.



 TOC 

3.  URL Syntax

A data store on an HTTP server has a URL like

http://host:port/path

To address its inner components directly, an extended URL syntax can be introduced

http://host:port/path""identifier?query_string
                     ^^\_____________________/
                     ||          |
                     ||          |
                     ||      URL extension
                empty string

in which an empty string "" separates the "standard" resource URL from the extension. Within the extension, the identifier defines what component to expose and the query_string dictates how to expose.



 TOC 

3.1.  Identifier



 TOC 

3.1.1.  Node

The meta information of node x is identified by identifier

/x1/x2/.../xn/x/

which is, in fact, an empty string "" prefixed by the node's full name using separator "/", i.e.,

""/x1/x2/.../xn/x/""

The data information of node x is currently not defined.



 TOC 

3.1.2.  Leaf

The meta information of leaf x is identified by identifier

/x1/x2/.../xn/x/

which is, in fact, an empty string "" prefixed by the leaf's full name using separator "/", i.e.,

""/x1/x2/.../xn/x/""

The data information of leaf x is identified by identifier

/x1/x2/.../xn/x[selector]

in which selector specifies a portion of the data. If selector is an empty string, it means the entire data.

The exact syntax of a selector depends on the w10n type involved. (see Section 6 below for more about w10n type).



 TOC 

3.2.  Query String

The query_string contains parameters of name-value pairs, used to direct server actions. The following parameters are currently defined:

(a) output -- value is a string specifying format of HTTP response: one of json, html, raw, etc.

(b) callback -- value is a string specifying a JavaScript function name used to wrap HTTP response in JSONP form, if value of parameter "output" is json.

(c) recache -- no value. If present, response cache must be refreshed.

(d) flatten -- no value. If present, multi-dimensional array in response is flattened.

(e) traverse -- no value. If present, all sub-nodes are traversed.

Please note neither parameter name nor its value is case-sensitive.



 TOC 

4.  HTTP Request

Depending on the HTTP method used, an HTTP request with a w10n URL as defined in Section 3 above can be a "w10n read" or a "w10n write".



 TOC 

4.1.  GET Request - Read

In a GET request, URL is

http://host:port/path""identifier?query_string

and message body is absent. Such a request retrieves (reads) meta or data information for a node or leaf identified by the URL.



 TOC 

4.2.  PUT Request - Write

In a PUT request, URL is

http://host:port/path""identifier?query_string

and message body contains data. Such a request saves data (writes) to a leaf identified by the URL.



 TOC 

5.  HTTP Response

At minimum, a w10n service must be able to respond in JSON format for any valid URL containing a meta information identifier, which always ends with a "/".

For the convenience of our discussion, only JSON format is used below.



 TOC 

5.1.  Node

As stated in Section 3 above, currently only meta information identifier is defined for a node.



 TOC 

5.1.1.  Meta

Response for meta information of a node is an object, consisting of members with pre-defined names:

{
    "name": string,
    "attributes": [...],
    "nodes": [...],
    "leaves": [...],
    "w10n": [...]
}

Currently only five (5) members are allowed. All members, except "attributes", are mandatory.



 TOC 

5.1.1.1.  "name"

Its value is a string, naming the node.



 TOC 

5.1.1.2.  "attributes"

Its value is an array of zero (0) or more objects:

[
    {
        "name": string,
        "value": ...
    },
    {
        "name": string,
        "value": ...
    },
    ...
]

Each object denotes an attribute and has two (2) and only two members: "name" and "value".



 TOC 

5.1.1.3.  "nodes"

Its value is an array of zero (0) or more objects:

[
    {
        "name": string,
        ...
    },
    {
        "name": string,
        ...
    },
    ...
]

Each object denotes a sub-node and, at minimum, contains member "name" with name of the sub-node as its value.

If there are a large number of sub-nodes and their names follow a common pattern, they can be represented by a single object that uses the pattern string plus a pre-defined prefix as its name.



 TOC 

5.1.1.4.  "leaves"

Its value is an array of zero (0) or more objects:

[
    {
        "name": string,
        ...
    },
    {
        "name": string,
        ...
    },
    ...
]

Each object denotes a leaf and, at minimum, contains member "name" with name of the leaf as its value.

If there are a large number of leaves and their names follow a common pattern, they can be represented by a single object that uses the pattern string plus a pre-defined prefix as its name.



 TOC 

5.1.1.5.  "w10n"

Its value is an array of five (5) objects:

[
    {
        "name": "spec",
        "value": string
    },
    {
        "name": "application",
        "value": string
    },
    {
        "name": "type",
        "value": string
    },
    {
        "name": "path",
        "value": string
    },
    {
        "name": "identifier",
        "value": string
    }
]

Each object has two (2) and only two members, namely, "name" and "value". Furthermore, value for member "name" is pre-defined and value for member "value" contains respective information such as version of w10n specification, name and version of application, webification type, date store path and node meta identifier.



 TOC 

5.1.2.  Data

Currently not defined.



 TOC 

5.2.  Leaf

As stated in Section 3 above, both meta and data information identifiers are defined for a leaf.



 TOC 

5.2.1.  Meta

Response for meta information of a leaf is an object, consisting of members with pre-defined names:

{
    "name": string,
    "attributes": [...],
    ...,
    "w10n": [...]
}

There can be more members depending on w10n type.

Member "name" and "w10n" are mandatory. Member "attributes" is optional.



 TOC 

5.2.1.1.  "name"

Its value is a string, naming the leaf.



 TOC 

5.2.1.2.  "attributes"

Its value is an array of zero (0) or more objects:

[
    {
        "name": string,
        "value": ...
    },
    {
        "name": string,
        "value": ...
    },
    ...
]

Each object denotes an attribute and has two (2) and only two members: "name" and "value".



 TOC 

5.2.1.3.  "w10n"

Its value is an array of five (5) objects:

[
    {
        "name": "spec",
        "value": string
    },
    {
        "name": "application",
        "value": string
    },
    {
        "name": "type",
        "value": string
    },
    {
        "name": "path",
        "value": string
    },
    {
        "name": "identifier",
        "value": string
    }
]

Each object has two (2) and only two members, namely, "name" and "value". Furthermore, value for member "name" is pre-defined and value for member "value" contains respective information such as version of w10n specification, name and version of application, webification type, date store path and leaf meta identifier.



 TOC 

5.2.2.  Data

Response of a URL with data information identifier may be in different formats: json, raw, etc. depending on w10n type and the value of parameter "output" in query_string.



 TOC 

5.2.2.1.  JSON

A JSON response for leaf data is a JSON object:

{
    "name": string,
    "type": string,
    "attributes": [...],
    "data": ...,
    ...,
    "w10n": [...]
}

which is similar to that of 5.2.1, but has additional members "type" and "data".



 TOC 

6.  Webification Type

For the same data store, there may be more than one way to webify it. Each way can be designated using a string, called w10n type.

To avoid potential conflict, this spec uses the following convention to assign w10n type:

major.minor

where major is a string about store type and minor a string about the particular way of webifying. The separator is ".", a period.

Furthermore, an experimental w10n type must be prefixed with "x" using "." as the separator, such as

x.major.minor

W10n type is always returned as element "type" in member "w10n" in a JSON response for meta or data information of an entity (node or leaf).



 TOC 

7. References

1 RFC 2616, “Hypertext Transfer Protocol -- HTTP/1.1.”
2 RFC 4627, “The application/json Media Type for JavaScript Object Notation (JSON).”
3 RFC 3986, “Uniform Resource Identifier (URI): Generic Syntax.”


 TOC 

Appendix A.  Copyrights

Copyright © 2001 – 2013 w10n.org

Hold harmless the author, and any lawful use is allowed.



 TOC 

Author's Address

  spec@w10n.org
  w10n.org