Expose documents via json rest.

Enable Shard Rest

The rest extenions needs to be configured with an endpoint map. The endpoint map defines which documents will be exposed by the rest controller, and what urls will be used to access them. Eg:

'zoop' => [
    'shard' => [
        'manifest' => [
            'default' => [
                'extension_configs' => [
                    'extension.rest' => [
                        'endpoint_map' => [
                            'users' => [
                                'class' => 'My\Users\Document',
                                'property' => 'username'
                            ]
                        ]
                    ]
                ]
            ]
        ]
    ]
]

Embedded Lists

To make embedded lists accessable via rest, configure them like this:

...
'endpoint_map' => [
    'users' => [
        'class' => 'My\Users\Document',
        'property' => 'username',
        'embedded_lists' => [
            'assets' => [
                'property' => 'name',
                'class' => 'My\Assets\Document'
            ]
        ]
    ]
]
...

Customize Route

Shard Module automatically configures the rest controller on the /rest route. You may wish to override that in your module config.

By default, the config above would expose the user with username toby at:

http://myserver.com/rest/users/toby

Access Control

If the Access Control extension is enabled, all permissions will be respected.

Get a single document.

To get a document use:

http://myserver.com/rest/user/toby

Partial documents

To get only some properties of a document use:

http://myserver.com/rest/user/toby?select(username,age)

Single nested document

Append the property name:

http://myserver.com/rest/user/toby/address

Single document from a nested list

To get one item from a list of documents append the property name and the id of the document you want:

http://myserver.com/rest/user/toby/assets/funky-car

Errors

Get a list of documents.

An array of documents will be returned when a list is requested, rather than a specific document. A successful response will include a contentRange: x-x/x header.

http://myserver.com/rest/user

Partial documents

http://myserver.com/rest/user?select(username,age)

Filter

http://myserver.com/rest/user?country=australia

And Filter

http://myserver.com/rest/user?country=australia&type=active

Or Filter

http://myserver.com/rest/user?country=[australia, usa]

Sort Ascending

http://myserver.com/rest/user?sort(+username)

Sort Decending

http://myserver.com/rest/user?sort(-username)

Multiple Sort

http://myserver.com/rest/user?sort(+country,+username)

Offset

HEADERS
range: items=2-25
http://myserver.com/rest/user

Nested List

http://myserver.com/rest/assets

Errors

Create a document

To create a new document, use a POST request, and place the json document in the request body.

POST
HEADERS
Content-type: application/json

CONTENT
{"username": "lucy", "age": 27}
http://myserver.com/rest/user

Single nested document

POST
HEADERS
Content-type: application/json

CONTENT
{"street": "Street Rd", "number": "45", city: "Sydney"}
http://myserver.com/rest/user/address

Single document from a nested list

POST
HEADERS
Content-type: application/json

CONTENT
{"make": "ford", "model": "stumpy"}
http://myserver.com/rest/user/assets/old-car

Create with reference

Add a reference to an already existing document.

POST
HEADERS
Content-type: application/json

CONTENT
{"username": "jsason", "country": {"$ref": "country/australia"}}
http://myserver.com/rest/user

Errors

Update a document.

Note: PUT will update all properties of a document. If you need to update only some of the properties of a doument, use PATCH.

The response from a successful PUT will always be a 204.

Update a document

PUT
HEADERS
Content-type: application/json

CONTENT
{"age": "18"}
http://myserver.com/rest/user/toby

Create via PUT

If the document selected for update does not exist, it will be created.

PUT
HEADERS
Content-type: application/json

CONTENT
{"age": "27"}
http://myserver.com/rest/user/lucy

Update single nested document

Append the property name:

PUT
HEADERS
Content-type: application/json

CONTENT
{"street": "Street Rd", "number": "45", city: "Sydney"}
http://myserver.com/rest/user/toby/address

Update single document in a nested list

To update one item from a list of documents append the property name and the id of the document you want:

PUT
HEADERS
Content-type: application/json

CONTENT
{"make": "gm", "model": "camero"}
http://myserver.com/rest/user/toby/assets/funky-car

Replace a whole list

PUT
HEADERS
Content-type: application/json

CONTENT
[
   {"username": "gumpy"},
   {"username": "sleepy"}
   {"username": "happy"}
]
http://myserver.com/rest/user

Update document id

A document id can be updated. To do so, include the new document id in the PUT data. Note that this will actually delete the existing document, and create a new document with the new id.

PUT
HEADERS
Content-type: application/json

CONTENT
{"username": "toby-different"}
http://myserver.com/rest/user/toby

Errors

Patch a document.

Note: PATCH will update a selection of properties on a document.

The response from a successful PATCH will always be a 204.

Patch a document

PATCH
HEADERS
Content-type: application/json

CONTENT
{"age": "18"}
http://myserver.com/rest/user/toby

Create via PATCH

If the document selected for patch does not exist, it will be created.

PATCH
HEADERS
Content-type: application/json

CONTENT
{"age": "27"}
http://myserver.com/rest/user/lucy

Patch single nested document

Append the property name:

PATCH
HEADERS
Content-type: application/json

CONTENT
{"street": "Street Rd"}
http://myserver.com/rest/user/toby/address

Patch single document in a nested list

To patch one item from a list of documents append the property name and the id of the document you want:

PATCH
HEADERS
Content-type: application/json

CONTENT
{"make": "gm", "model": "camero"}
http://myserver.com/rest/user/toby/assets/funky-car

Patch whole list

Patching a list will add the supplied items to the list, without removing the existing items.

PATCH
HEADERS
Content-type: application/json

CONTENT
[
   {"username": "gumpy"},
   {"username": "sleepy"}
   {"username": "happy"}
]
http://myserver.com/rest/user

Patch document id

A document id can be patched. To do so, include the new document id in the PATCH data. Note that this will actually delete the existing document, and create a new document with the new id.

PATCH
HEADERS
Content-type: application/json

CONTENT
{"username": "toby-different"}
http://myserver.com/rest/user/toby

Errors

Delete a document.

The response from a successful DELETE will always be a 204.

Delete a document

DELETE
HEADERS
Content-type: application/json

http://myserver.com/rest/user/toby

Delete a list

DELETE
HEADERS
Content-type: application/json

http://myserver.com/rest/user

Delete single nested document

Append the property name:

DELETE
HEADERS
Content-type: application/json

http://myserver.com/rest/user/toby/address

Delete single document in a nested list

To delete one item from a list of documents append the property name and the id of the document you want:

DELETE
HEADERS
Content-type: application/json

http://myserver.com/rest/user/toby/assets/funky-car

Errors

Execute multiple requests at once

A batch request is always a POST to the batch endpoint. The POST content describes the requests which should be executed in order. The response content will describe the result of each request.

For example, this batch request will be the same as executing the nine separate requests in order:

POST
HEADERS
Content-type: application/json

CONTENT
{
    "get single author": {
        "uri": "/rest/author/james",
        "method": "GET"
    },
    "get author list": {
        "uri": "/rest/author",
        "method": "GET"
    },
    "get author list of partials": {
        "uri": "/rest/author?select(name)",
        "method": "GET"
    },
    "get filtered author list": {
        "uri": "/rest/author?country=germany",
        "method": "GET"
    },
    "get author list offset": {
        "uri": "/rest/author",
        "method": "GET",
        "headers": {
            "Range": "items=2-100"
        }
    },
    "replace game list": {
        "uri": "/rest/game",
        "method": "POST",
        "content": {"name": "forbidden-island", "type": "co-op"}
    },
    "delete an author": {
        "uri": "/rest/author/harry",
        "method": "DELETE"
    },
    "update a game": {
        "uri": "/rest/game/feed-the-kitty",
        "method": "PUT",
        "content": {"type": "childrens", "author": {"$ref": "author/harry"}}
    },
    "patch a game": {
        "uri": "/rest/game/feed-the-kitty",
        "method": "PATCH",
        "content": {"type": "kids"}
    }
}

http://myserver.com/rest/batch

The response object might look like:

{
    "get single author": {
        "status": 200,
        "content": { ... }
    },
    "get author list": {
        "status": 200,
        "headers": {
            "Content-Range": "x-x/x"
        },
        "content": [ ... ]
    },
    "get author list of partials": {
        "status": 200,
        "headers": {
            "Content-Range": "x-x/x"
        },
        "content": [ ... ]
    },
    "get filtered author list": {
        "status": 200,
        "headers": {
            "Content-Range": "x-x/x"
        },
        "content": [ ... ]
    },
    "get author list offset": {
        "status": 200,
        "headers": {
            "Content-Range": "x-x/x"
        },
        "content": [ ... ]
    },
    "replace game list": {
        "status": 204
    },
    "delete an author": {
        "status": 204
    },
    "update a game": {
        "status": 204
    },
    "patch a game": {
        "status": 204
    }
}