diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api-reference.md | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 0000000..7f7a465 --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,219 @@ +# 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 . +``` + +TODO do not return list + +```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's description" +} +EOF +``` + +The endpoint returns the full, updated entity. + +TODO return full, updated entity, return single entity + +```json +[] +``` + +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 return full, updated entity, return single entity + +```json +[] +``` + +## 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 . +``` + +TODO return deleted entity, only one entity + +```json +[] +``` |