endpoints.remarkup

# Built-in endpoints

Sealious automatically creates endpoints for all the collections defined within
your app. All endpoins automatically take care of policy enforcement, so you
don't have to worry about implementing logic of who can do what. Just make sure
that the policies are set up properly for each collection and they will be
enforced.

NOTE: Some query params are expected to have complex, sometimes even nested
structure. When the documentation refers to key/value-formatted query params,
use [] syntax, so to send `{filter: {name: "Reksio", age: 34}}`, use
`filter[name]=Reksio&filter[age]=34`. See the [qs
module](https://github.com/ljharb/qs) for more details.

## User/Session management

### Register:

`POST /api/v1/collections/registration-intents`

params: email

Starts user registration flow. THe user needs to confirm the email first, and
then is redirected to a form that lets them choose their username.

### Log in:

`POST /api/v1/sessions/`

params: username, password

Attempts to log the user in. If the login is successfull, a cookie with session
ID is set. Otherwise, an error message in JSON form is returned.

Why isn't it just `POST /api/v1/login`? It's simply to mainain the REST-ful
semantics. When you log in, you actually want to create (`POST`) a new session
(`/api/v1/sessions`).

### Log out:

`DELETE /api/v1/collections/sessions/current`

Deletes the current session from DB. No params needed

### Who am i?

In order to check who the currently logged in user is, they can call

`GET /api/v1/collections/users/me`

### Request a password reset:

`POST /api/v1/collections/password-reset-intents`

params: email

Begins the password reset flow. If the email exists in the database, a message
with reset link is sent to the user.

### Static forms

There routes set up for some static forms, including:

-   `GET /account-creation-details` asks for user data when creating an account
-   `POST /finalize-registration-intent` finishes user creation.
    `/account-creation-details` contains a form that POSTs to this endpoint.
-   `POST /finalize-password-reset`
-   `GET /confirm-password-reset`

## Collection endpoints

Each collection gets a full REST-ful API endpoint. These endpoints work for both
the collections created by you, //as well as// for all built-in collections:

-   `users`
-   `sessions`

### List all elements within the collection

`GET /api/v1/collections/:collection_name`

#### Query Params:

-   `filter` - key/value. Maps field names to the desired values. Example:
    `?filter[name]=Hoover&filter[age][gt]=18`
-   `sort` - key/value. Forces the output to be sorted by given field. Example:
    `?sort[favorite_number]=desc`. Sort order is `desc` or `asc`
-   `pagination` - key/value. Keys are: `page` (which page to display), `items`
    (how many items per page), `forward_buffer` (return this many more
    additional items per page than specified in `items`. Useful when trying to
    establish whether or not there is a next page to display)
-   `attachments` - key/value. keys are field-names, values are field-type specific.
    Whether or not to fetch attachments related to given field, and in what
    form. Currently supported only by `single-reference` and
    `reverse-single-reference` field types.
-   `format` key/value. Some fields can have different outputs depending on the
    provided format.

#### Examples

```
# show only seals named Hoover:
GET /api/v1/collections/seals?filter[name]=Hoover

# sort by age, filter by object_field.weight:
GET /api/v1/collections/seals?filter[object_field][weight]=280&sort[age]=asc

# 10 items per page, show items 11-20:
GET /api/v1/collections/seals?filter[name]=Hoover?pagination[items]=10&page=2
```

Example response:

```
lang=json
{
    "attachments": {},
    "fields_with_attachments": [],
    "items": [
        {
            "done": false,
            "id": "YwviNwK-X",
            "title": "Remember to push to master"
        },
        {
            "done": false,
            "id": "O6-WocIJs",
            "title": "Write docs"
        },
    ]
}
```

### Get an item by ID

`GET /api/v1/collections/:collection_name/:id`

#### Query params:

-   `attachments` - key/value. keys are field-names, values are field-type specific.
    Whether or not to fetch attachments related to given field, and in what
    form. Currently supported only by `single-reference` and
    `reverse-single-reference` field types.
-   `format` key/value. Some fields can have different outputs depending on the
    provided format.

#### Examples

```
# get a task with id xyz123
GET /api/v1/collections/tasks/xyz123
```

Example response:

```
lang=json
{
    "attachments": {},
    "fields_with_attachments": [],
    "items": [
        {
            "done": false,
            "id": "YwviNwK-X",
            "title": "Write docs"
        }
    ]
}
```

```
# get a task with id xyz123 and inline bodies of the attachments from field 'roles'
GET /api/v1/collections/tasks/xyz123?attachments[roles]=true
```

Example response:

```
lang=json
{
    "attachments": {
        "o0wb6n": { "name": "admin" },
        "kegfd7qg": { "name": "user" }
    },
    "fields_with_attachments": [],
    "items": [
        {
            "done": false,
            "id": "YwviNwK-X",
            "title": "Write docs",
            "roles": ["o0wb6n", "kegfd7qg"]
        }
    ]
}
```

### Create an item

`POST /api/v1/collections/:collection_name`

#### Request body:

Fill in all fields defined within the collection as JSON or form-data.

#### Examples

```
http POST http://localhost:8080/api/v1/collections/tasks title="some title" done=false
```

### Edit an existing item

`PATCH /api/v1/collections/:collection_name/:id`

`PUT /api/v1/collections/:collection_name/:id`

#### Request body:

JSON or form-data. When using PATCH, only send the fields that you want to change. When using PUT, send all fields you want saved.

When using PUT, ommiting a field means "delete it's value". When using PATCH, omitting a field means "leave it unchanged".

#### Examples

```
http PATCH https://localhost:8080/api/v1/collections/tasks/YwviNwK-X done=true
```

### Delete an item

`DELETE /api/v1/collections/:collection_name:/id`

No query params or body params.

#### Examples

```
http DELETE https://localhost:8080/api/v1/collections/tasks/YwviNwK-X
```