# REST API Reference

## Collection type API

### Create collection type entities

You can create a new collection type entities. If the collection does not exist, it will automatically be created.

The following call to `POST /api/rest/collection/entity` creates a new entity with fields `name` and `description`.

```console
curl -X POST http://localhost:8081/api/rest/collection/entity --data @- <<'EOF' | jq .
{
  "name": "Entity 1",
  "description": "Description of entity 1"
}
EOF
```

Note that the created entity is returned, including the meta field `$fileName`.

```json
{
  "$fileName": "9474f0eb-06d7-4fd8-b89e-0ce996962508.json",
  "description": "Description of entity 1",
  "name": "Entity 1"
}
```

To demonstrate other API capabilities, go ahead and create a second entity.

```console
curl -X POST http://localhost:8081/api/rest/collection/entity --data @- <<'EOF' | jq .
{
  "name": "Entity 2",
  "description": "Description of entity 2"
}
EOF
```

```json
{
  "$fileName": "ccccc18c-f3dc-4f98-b4d2-290ef76adb6b.json",
  "description": "Description of entity 2",
  "name": "Entity 2"
}
```

### Retrieving a collection type's schema

With having entities, a collection schema is automatically inferred, and can be queried.

```console
curl http://localhost:8081/api/rest/collection/entity/schema | jq .
```

As one would expect, the schema lists the fields `name`, `description` as required fields of type `string`.

```json
{
  "$id": "entity.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "$fileName": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "$fileName",
    "description",
    "name"
  ],
  "title": "entity",
  "type": "object"
}
```

### Retrieving a single collection entity

Single collection entities can be retrieved using their unique `$fileName` identifier.

```console
curl http://localhost:8081/api/rest/collection/entity/9474f0eb-06d7-4fd8-b89e-0ce996962508.json | jq .
```

```json
{
  "$fileName": "9474f0eb-06d7-4fd8-b89e-0ce996962508.json",
  "description": "Description of entity 1",
  "name": "Entity 1"
}
```

### Retrieving all collection entities

All collection entities can be requested as well.

```console
curl http://localhost:8081/api/rest/collection/entity | jq .
```

```json
[
  {
    "$fileName": "9474f0eb-06d7-4fd8-b89e-0ce996962508.json",
    "description": "Description of entity 1",
    "name": "Entity 1"
  },
  {
    "$fileName": "ccccc18c-f3dc-4f98-b4d2-290ef76adb6b.json",
    "description": "Description of entity 2",
    "name": "Entity 2"
  }
]
```

### Updating a collection entity

Updating a collection entity is possible by send only select fields.

```console
curl -X PUT http://localhost:8081/api/rest/collection/entity/ccccc18c-f3dc-4f98-b4d2-290ef76adb6b.json --data @- <<'EOF' | jq .
{
    "description": "Entity 2 description"
}
EOF
```

The endpoint returns the full, updated entity.

```json
{
  "$fileName": "ccccc18c-f3dc-4f98-b4d2-290ef76adb6b.json",
  "description": "Entity 2 description",
  "name": "Entity 2"
}
```

Fields can be deleted setting them their values to `null`.

```console
curl -X PUT http://localhost:8081/api/rest/collection/entity/ccccc18c-f3dc-4f98-b4d2-290ef76adb6b.json --data @- <<'EOF' | jq .
{
    "description": null
}
EOF
```

Again, the response contains the full entity after the update.

TODO sanitize `null` fields

```json
{
  "$fileName": "ccccc18c-f3dc-4f98-b4d2-290ef76adb6b.json",
  "description": null,
  "name": "Entity 2"
}
```

## Retrieving the global schema version

Because we have deleted a required field, we have changed the `entity` collectiontype's schema.

The collection type's schema endpoint reflects that change.

```console
curl http://localhost:8081/api/rest/collection/entity/schema | jq .
```

```json
{
  "$id": "entity.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "$fileName": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "$fileName",
    "name"
  ],
  "title": "entity",
  "type": "object"
}
```

What's more, the global schema version records this backwards-incompatible (breaking) change.

```console
curl http://localhost:8081/api/rest/schemaVersion | jq .
```

```json
"1.2.0"
```

### Deleting collection entities

```console
curl -X DELETE http://localhost:8081/api/rest/collection/entity/9474f0eb-06d7-4fd8-b89e-0ce996962508.json | jq .
```

```json
{
  "$fileName": "9474f0eb-06d7-4fd8-b89e-0ce996962508.json",
  "description": "Description of entity 1",
  "name": "Entity 1"
}
```