[Jackrabbit Wiki] Update of "frm/HttpOperations" by frm

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jackrabbit Wiki" for change notification.

The "frm/HttpOperations" page has been changed by frm:
https://wiki.apache.org/jackrabbit/frm/HttpOperations

New page:
= HTTP Operations =

This document provides a description of the HTTP implementation of the operations exposed by the Oak Remote API.

== Authentication ==

This section relies on the HTTP/1.1 Authentication framework defined by RFC7235. The idea is that an Oak server may define different authentication schemes, while the client may choose one of them according to his particular needs.

Authentication information is mandatory for every method described below, unless differently specified.

=== Basic ===

The basic authentication uses the authentication scheme described in Section 2 of RFC2617. The client provides a user name and password that will be authenticated by the repository using the normal login procedure.

=== Impersonation ===

The impersonation authentication is a variant on the basic authenticatino already defined by RFC2617. The differences are the following:

 * the authentication scheme to be used is `Impersonation` instead of `Basic`.

 * the client must include an authentication parameter named `impersonate` containing the name of a user.

Please note that, like in the basic authentication, the client still has to provide a user name and password encoded in Base64 and the realm where authentication should be performed in.

If this authentication strategy is chosen, the server executes the following actions:

 * the server performs a repository login using the user name and password provided by the client in the `Authorization` header. 

 * if the login succeeds, the server reads the user name in the `impersonate` authentication parameter and performs an impersonation using this user name. The rest of the request will be evaluated using the impersonated session.

== Read a revision ==

{{{
POST /revisions
}}}

In case of success, the server returns a `201` response with a content type of `application/json`. The body of the respnose is a JSON object, where the revision is the value of the `revision` property.

{{{
{
  "revision": "..."
}
}}}

The value of the `revision` property is an opaque value whose format and semantics are implementation dependent.


== Read a tree ==

{{{
GET /revisions/:revision/tree/:path
}}}

The `:revision` part of the URL is the revision that represents the state of the repository used when reading. A value for this parameter is obtained by using a dedicated method of this API.

The `:path` part of the URL is the path of the node in the repository that will be used as a root for the read operation.

Request parameters:

 * `revision` - the revision that represents the state of the repository used when reading. A value for this parameter is obtained by using a dedicated method of this API. This parameter is mandatory and is a single-value parameter.

 * `depth` - the maximum depth of the tree returned by the response. This parameter is optional and is a single-value parameter.

 * `properties` - a glob representing a property filter for the returned tree. This parameter is optional and is a multi-value parameter. Multiple instances of this parameter can be included to specify different property filters.

 * `children` - a glob representing a filter for the child nodes included in the returned tree. This parameter is optional and is a multi-value parameter. Multiple instances of this parameter can be included to specify different child node filters.

 * `binaries` - the maximum number of bytes under which binary data are inlined in the response. This parameter is optional and is a single-value parameter.

In case of success, the server returns a `200` response with a content type of `application/json`. The body of the response is a JSON object representing a tree node. If the root of the tree was not found, the JSON document will simply have the value `null`.

A node is represented with a JSON object with the following structure:

{{{
{
  "properties": {
    "foo": {"type": "string", "value": "bar"},
    "baz": {"type": "uri", "value": "http://acme.com"},
    "qux": {"type": "booleans", "value": [true, false, true]}
  },
  "children": {
    "bob": null,
    "sue": null
  }
}
}}}

Property values are serialized according to the following rules:

{{{
Repository type   JSON type   Type name         Description
===============   =========   =========         ===========
STRING            string      "string"
BINARY            string      "binary"          Binary value encoded in Base64.
BINARY            string      "binaryId"        Implementation-dependent reference to a binary value.
LONG              number      "long"            
DOUBLE            number      "double"
DATE              string      "date"            Representation of the date in the format defined by ISO 8601.
BOOLEAN           boolean     "boolean"
NAME              string      "name"
PATH              string      "path"
REFERENCE         string      "reference"
WEAK REFERENCE    string      "weakReference"
URI               string      "uri"
DECIMAL           string      "decimal"         String serialization of the decimal number.
}}}

== Write content ==

{{{
PATCH /revisions/:revision/tree
}}}

The `:revision` part of the URL specifies the revision the patch should be applied to. A value for this parameter is obtained by using a dedicated method of this API.

The request must have a content type of `application/json` and its body must contain the set of operations to apply to the content represented according to the following rules.

The set of operations must be contained inside a JSON array. The elements of this array are the operations. Every operation is represented by a JSON object. An operation can be of one of six different types: add, remove, set, unset, copy and move.

The following example patch shows all of the available operations and their serialization format.

{{{
[
  {
    "type": "add",
    "path": "/a/b/c",
    "properties": {
      "foo": {"type": "string", "value": "bar"},
      "baz": {"type": "uri", "value": "http://acme.com"},
      "qux": {"type": "booleans", "value": [true, false, true]}
    }
  },
  {
    "type": "remove",
    "path": "/a/b/c"
  },
  {
    "type": "set",
    "path": "/a/b/c",
    "name": "foo",
    "type": "string",
    "value": "bar"
  },
  {
    "type": "unset",
    "path": "/a/b/c",
    "name": "foo"
  },
  {
    "type": "move",
    "from": "/x/y",
    "to": "/p/q"
  },
  {
    "type": "copy",
    "from": "/x/y",
    "to": "/r/s"
  }
]
}}}

In case of success, the server returns a `201` response with a content type of `application/json`. The body of the respnose is a JSON object, where the revision is the value of the `revision` property.

{{{
{
  "revision": "..."
}
}}}

The value of the `revision` property is an opaque value whose format and semantics are implementation dependent.