# info.description
An API to manage Objects.

# Introduction

An OBJECT is of a certain OBJECTTYPE (defined in the Objecttypes API). An
OBJECT has a few core attributes that every OBJECT (technically a RECORD,
see below) has, although these attributes can sometimes be empty. They are
attributes like `geometry` and some administrative attributes. The data that
describes the actual object is stored in the `data` attribute and follows
the JSON schema as given by the OBJECTTYPE.

## Validation

When an OBJECT is created or changed the `OBJECT.type` attribute refers to the
matching OBJECTTYPE in the Objecttypes API. The RECORD always indicates which
OBJECTTYPE-VERSION is used, shown in the `RECORD.typeVersion` attribute.

Using these 2 attributes, the appropriate JSON schema is retrieved from the
Objecttypes API and the OBJECT data is validated against this JSON schema.

## History

Each OBJECT has 1 or more RECORDs. A RECORD contains the data of an OBJECT
at a certain time. An OBJECT can have multiple RECORDS that describe the
history of that OBJECT. Changes to an OBJECT actually create a new RECORD
under the OBJECT and leaves the old RECORD as is.

### Material and formal history

History can be seen from 2 perspectives: formal and material history. The
formal history describes the history as it should be (stored in the
`startAt` and `endAt` attributes). The material history describes the
history as it was administratively processed (stored in the `registeredAt`
attribute).

The difference is that an object could be created or updated in the real
world at a certain point in time but the administrative change (ie. save or
update the object in the Objects API) can be done at a later time. The
query parameters `?date=2021-01-01` (formal history) and
`?registrationDate=2021-01-01` (material history) allow for querying the
RECORDS as seen from both perspectives, and can yield different results.

### Corrections

RECORDs cannot be deleted or changed once saved. If an error was made to
a RECORD, the RECORD can be "corrected" by saving a new RECORD and indicate
that it corrects a previous RECORD. This is done via the attribute
`correctionFor`.

### Deletion

Although OBJECTs can be deleted, it is sometimes better to set the
`endDate` of an OBJECT. Deleting an OBJECT also deletes all RECORDs in
accordance with privacy laws.

# Authorizations

The API uses API-tokens that grant certain permissions. The API-token is
passed via a header, like this: `Authorization: Token <token>`

# Notifications

When OBJECTs are created, updated or deleted via the API, notifications of
these operations are published to the configured Notifications API in the
`objecten` channel.

# paths./objects.get.description
Retrieve a list of OBJECTs and their actual RECORD. The actual record is defined as if the query parameter `date=<today>` was given.

# paths./objects.get.parameters[].description
The desired 'Coordinate Reference System' (CRS) of the response data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects.get.parameters[].description
Only include objects that have attributes with certain values.

A valid parameter value has the form `key__operator__value`.
`key` is the attribute name, `operator` is the comparison operator to be used and `value` is the attribute value.
Note: Values can be string, numeric, or dates (ISO format; YYYY-MM-DD).

Valid operator values are:
* `exact` - equal to
* `gt` - greater than
* `gte` - greater than or equal to
* `lt` - lower than
* `lte` - lower than or equal to
* `icontains` - case-insensitive partial match
* `in` - in a list of values separated by `|`

`value` may not contain double underscore or comma characters.
`key` may not contain comma characters and includes double underscore only if it indicates nested attributes.



Example: in order to display only objects with `height` equal to 100, query `data_attr=height__exact__100`
should be used. If `height` is nested inside `dimensions` attribute, query should look like
`data_attr=dimensions__height__exact__100`

This filter is very similar to the old `data_attrs` filter, but it has two differences:

* `value` may contain commas
* only one filtering expression is allowed

If you want to use several filtering expressions, just use this `data_attr` several times in the query string.
Example: `data_attr=height__exact__100&data_attr=naam__icontains__boom`

# paths./objects.get.parameters[].description
**DEPRECATED: Use 'data_attr' instead**.
Only include objects that have attributes with certain values.
Data filtering expressions are comma-separated and are structured as follows:

A valid parameter value has the form `key__operator__value`.
`key` is the attribute name, `operator` is the comparison operator to be used and `value` is the attribute value.
Note: Values can be string, numeric, or dates (ISO format; YYYY-MM-DD).

Valid operator values are:
* `exact` - equal to
* `gt` - greater than
* `gte` - greater than or equal to
* `lt` - lower than
* `lte` - lower than or equal to
* `icontains` - case-insensitive partial match
* `in` - in a list of values separated by `|`

`value` may not contain double underscore or comma characters.
`key` may not contain comma characters and includes double underscore only if it indicates nested attributes.



Example: in order to display only objects with `height` equal to 100, query `data_attrs=height__exact__100`
should be used. If `height` is nested inside `dimensions` attribute, query should look like
`data_attrs=dimensions__height__exact__100`

`value` may not contain comma, since commas are used as separator between filtering expressions.
If you want to use commas in `value` you can use `data_attr` query parameter.

# paths./objects.get.parameters[].description
Search in all `data` values of string properties.

# paths./objects.get.parameters[].description
Display record data for the specified material date, i.e. the specified date would be between `startAt` and `endAt` attributes. The default value is today

# paths./objects.get.parameters[].description
Comma-separated fields, which should be displayed in the response. For example: 'url, uuid, record__geometry'.

# paths./objects.get.parameters[].description
Comma-separated fields, which are used to order results. For descending order use '-' as prefix. Nested fields are also supported. For example: '-record__data__length,record__index'.

# paths./objects.get.parameters[].description
A page number within the paginated result set.

# paths./objects.get.parameters[].description
Display record data for the specified registration date, i.e. the specified date would be between `registrationAt` attributes of different records

# paths./objects.get.parameters[].description
Url reference to OBJECTTYPE in Objecttypes API

# paths./objects.get.parameters[].description
Display record data for the specified type version

# paths./objects.get.responses.200.headers.Content-Crs.description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects.get.responses.200.headers.X-Unauthorized-Fields.description
List of fields that are not allowed to display if the field-based authorization is turned on. The value has the following format: `objectType1:fieldA,fieldB; objectType2:fieldC,fieldD`

# paths./objects.post.description
Create an OBJECT and its initial RECORD.

# paths./objects.post.parameters[].description
The desired 'Coordinate Reference System' (CRS) of the response data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects.post.parameters[].description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects.post.responses.201.headers.Content-Crs.description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}.get.description
Retrieve a single OBJECT and its actual RECORD. The actual record is defined as if the query parameter `date=<today>` was given.

# paths./objects/{uuid}.get.parameters[].description
The desired 'Coordinate Reference System' (CRS) of the response data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}.get.parameters[].description
Comma-separated fields, which should be displayed in the response. For example: 'url, uuid, record__geometry'.

# paths./objects/{uuid}.get.responses.200.headers.Content-Crs.description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}.get.responses.200.headers.X-Unauthorized-Fields.description
List of fields that are not allowed to display if the field-based authorization is turned on. The value has the following format: `objectType1:fieldA,fieldB; objectType2:fieldC,fieldD`

# paths./objects/{uuid}.put.description
Update the OBJECT by creating a new RECORD with the updates values.

# paths./objects/{uuid}.put.parameters[].description
The desired 'Coordinate Reference System' (CRS) of the response data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}.put.parameters[].description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}.put.responses.200.headers.Content-Crs.description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}.patch.description
Update the OBJECT by creating a new RECORD with the updates values. The provided `record.data` value will be merged recursively with the existing record data.

# paths./objects/{uuid}.patch.parameters[].description
The desired 'Coordinate Reference System' (CRS) of the response data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}.patch.parameters[].description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}.patch.responses.200.headers.Content-Crs.description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}.delete.description
Delete an OBJECT and all RECORDs belonging to it.

# paths./objects/{uuid}/{index}.get.description
Retrieve the specified OBJECT given an UUID and INDEX.

# paths./objects/{uuid}/{index}.get.parameters[].description
The desired 'Coordinate Reference System' (CRS) of the response data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}/{index}.get.responses.200.headers.Content-Crs.description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}/history.get.parameters[].description
The desired 'Coordinate Reference System' (CRS) of the response data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/{uuid}/history.get.parameters[].description
A page number within the paginated result set.

# paths./objects/{uuid}/history.get.responses.200.headers.Content-Crs.description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/search.post.parameters[].description
The desired 'Coordinate Reference System' (CRS) of the response data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/search.post.parameters[].description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./objects/search.post.parameters[].description
A page number within the paginated result set.

# paths./objects/search.post.requestBody.content.application/json.schema.allOf[].properties.type.description
Url reference to OBJECTTYPE in Objecttypes API

# paths./objects/search.post.requestBody.content.application/json.schema.allOf[].properties.data_attrs.description
**DEPRECATED: Use 'data_attr' instead**.
Only include objects that have attributes with certain values.
Data filtering expressions are comma-separated and are structured as follows:

A valid parameter value has the form `key__operator__value`.
`key` is the attribute name, `operator` is the comparison operator to be used and `value` is the attribute value.
Note: Values can be string, numeric, or dates (ISO format; YYYY-MM-DD).

Valid operator values are:
* `exact` - equal to
* `gt` - greater than
* `gte` - greater than or equal to
* `lt` - lower than
* `lte` - lower than or equal to
* `icontains` - case-insensitive partial match
* `in` - in a list of values separated by `|`

`value` may not contain double underscore or comma characters.
`key` may not contain comma characters and includes double underscore only if it indicates nested attributes.



Example: in order to display only objects with `height` equal to 100, query `data_attrs=height__exact__100`
should be used. If `height` is nested inside `dimensions` attribute, query should look like
`data_attrs=dimensions__height__exact__100`

`value` may not contain comma, since commas are used as separator between filtering expressions.
If you want to use commas in `value` you can use `data_attr` query parameter.

# paths./objects/search.post.requestBody.content.application/json.schema.allOf[].properties.data_attr.description
Only include objects that have attributes with certain values.

A valid parameter value has the form `key__operator__value`.
`key` is the attribute name, `operator` is the comparison operator to be used and `value` is the attribute value.
Note: Values can be string, numeric, or dates (ISO format; YYYY-MM-DD).

Valid operator values are:
* `exact` - equal to
* `gt` - greater than
* `gte` - greater than or equal to
* `lt` - lower than
* `lte` - lower than or equal to
* `icontains` - case-insensitive partial match
* `in` - in a list of values separated by `|`

`value` may not contain double underscore or comma characters.
`key` may not contain comma characters and includes double underscore only if it indicates nested attributes.



Example: in order to display only objects with `height` equal to 100, query `data_attr=height__exact__100`
should be used. If `height` is nested inside `dimensions` attribute, query should look like
`data_attr=dimensions__height__exact__100`

This filter is very similar to the old `data_attrs` filter, but it has two differences:

* `value` may contain commas
* only one filtering expression is allowed

If you want to use several filtering expressions, just use this `data_attr` several times in the query string.
Example: `data_attr=height__exact__100&data_attr=naam__icontains__boom`

# paths./objects/search.post.requestBody.content.application/json.schema.allOf[].properties.date.description
Display record data for the specified material date, i.e. the specified date would be between `startAt` and `endAt` attributes. The default value is today

# paths./objects/search.post.requestBody.content.application/json.schema.allOf[].properties.registrationDate.description
Display record data for the specified registration date, i.e. the specified date would be between `registrationAt` attributes of different records

# paths./objects/search.post.requestBody.content.application/json.schema.allOf[].properties.typeVersion.description
Display record data for the specified type version

# paths./objects/search.post.requestBody.content.application/json.schema.allOf[].properties.data_icontains.description
Search in all `data` values of string properties.

# paths./objects/search.post.requestBody.content.application/json.schema.allOf[].properties.ordering.description
Comma-separated fields, which are used to order results. For descending order use '-' as prefix. Nested fields are also supported. For example: '-record__data__length,record__index'.

# paths./objects/search.post.responses.200.headers.Content-Crs.description
The 'Coordinate Reference System' (CRS) of the request data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is the same as WGS84).

# paths./permissions.get.description
Retrieve a list of permissions available for the user

# paths./permissions.get.parameters[].description
A page number within the paginated result set.

# components.schemas.HistoryRecord.properties.index.description
Incremental index number of the object record.

# components.schemas.HistoryRecord.properties.typeVersion.description
Version of the OBJECTTYPE for data in the object record

# components.schemas.HistoryRecord.properties.geometry.description
Point, linestring or polygon object which represents the coordinates of the object. Geometry can be added only if the related OBJECTTYPE allows this (`OBJECTTYPE.allowGeometry = true` or `OBJECTTYPE.allowGeometry` doesn't exist)

# components.schemas.HistoryRecord.properties.registrationAt.description
The date when the record was registered in the system

# components.schemas.HistoryRecord.properties.correctionFor.description
Index of the record corrected by the current record

# components.schemas.HistoryRecord.properties.correctedBy.description
Index of the record, which corrects the current record

# components.schemas.ModeEnum.description
* `read_only` - Read-only
* `read_and_write` - Read and write

# components.schemas.Object.description
this mixin allows selecting fields for serializer in the query param
It also supports nested fields.

# components.schemas.Object.properties.url.description
URL reference to this object. This is the unique identification and location of this object.

# components.schemas.Object.properties.type.description
Url reference to OBJECTTYPE in Objecttypes API

# components.schemas.ObjectRecord.properties.index.description
Incremental index number of the object record.

# components.schemas.ObjectRecord.properties.typeVersion.description
Version of the OBJECTTYPE for data in the object record

# components.schemas.ObjectRecord.properties.geometry.description
Point, linestring or polygon object which represents the coordinates of the object. Geometry can be added only if the related OBJECTTYPE allows this (`OBJECTTYPE.allowGeometry = true` or `OBJECTTYPE.allowGeometry` doesn't exist)

# components.schemas.ObjectRecord.properties.registrationAt.description
The date when the record was registered in the system

# components.schemas.ObjectRecord.properties.correctionFor.description
Index of the record corrected by the current record

# components.schemas.ObjectRecord.properties.correctedBy.description
Index of the record, which corrects the current record

# components.schemas.PatchedObject.description
this mixin allows selecting fields for serializer in the query param
It also supports nested fields.

# components.schemas.PatchedObject.properties.url.description
URL reference to this object. This is the unique identification and location of this object.

# components.schemas.PatchedObject.properties.type.description
Url reference to OBJECTTYPE in Objecttypes API

# components.schemas.Permission.properties.type.description
Url reference to OBJECTTYPE in Objecttypes API

# components.schemas.Permission.properties.mode.description
Permission mode

* `read_only` - Read-only
* `read_and_write` - Read and write

# components.schemas.Permission.properties.fields.description
Fields allowed for this token in relation to objecttype versions. Supports only first level of the `record.data` properties

# components.securitySchemes.tokenAuth.description
Token-based authentication with required prefix "Token"