diff --git a/README.NL.rst b/README.NL.rst index befc633c..77730bb5 100644 --- a/README.NL.rst +++ b/README.NL.rst @@ -1,9 +1,9 @@ -============ -Objecten API -============ +============= +Open Objecten +============= :Version: 3.6.0 -:Source: https://github.com/maykinmedia/objecttypes-api +:Source: https://github.com/maykinmedia/objects-api :Keywords: objecten, assets, zaakobjecten |docs| @@ -17,16 +17,12 @@ Ontwikkeld door `Maykin Media B.V.`_ in opdracht van de gemeente Utrecht. Introductie =========== -De Objecten API heeft als doel om uiteenlopende objecten eenvoudig te kunnen -registreren en ontsluiten in een gestandaardiseerd formaat. De Objecten API kan -door elke organisatie ingezet worden om de voor haar interessante objecten te -beheren. Ook kan een organisatie er voor kiezen een Objecten API in te zetten -voor Open Data, waarbij de geregistreerde objecten publiekelijk toegankelijk +Open Objecten heeft als doel om uiteenlopende typen objecten op een dynamische wijze te standaardiseren en om te voorkomen dat +voor elk (eenvoudig) object een volledige API wordt opgezet. instanties van objecten kunnen eenvouding worden geregistreerd en +ontsloten in een gestandaardiseerd formaat. De Objecten API kan door elke organisatie ingezet worden om de voor haar interessante objecten te +beheren. Ook kan een organisatie er voor kiezen een Objecten API in te zetten voor Open Data, waarbij de geregistreerde objecten publiekelijk toegankelijk zijn. -Om het formaat van objecten, de zogenoemde objecttypen, vast te leggen wordt -gebruik gemaakt van de landelijke en/of een lokale `Objecttypen API`_. - API specificatie ================ @@ -130,7 +126,7 @@ goed getest en beschikbaar als Docker image. Quickstart ---------- -1. Download en start de Objecten API: +1. Download en start Open Objecten: .. code:: bash @@ -165,8 +161,6 @@ Licensed under the EUPL_ .. _`Maykin Media B.V.`: https://www.maykinmedia.nl -.. _`Objecttypen API`: https://github.com/maykinmedia/objecttypes-api - .. _`EUPL`: LICENSE.md .. |build-status| image:: https://github.com/maykinmedia/objects-api/workflows/ci/badge.svg?branch=master diff --git a/README.rst b/README.rst index e65f728e..49ea3ae8 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,6 @@ -=========== -Objects API -=========== +============= +Open Objecten +============= :Version: 3.6.0 :Source: https://github.com/maykinmedia/objects-api @@ -8,7 +8,7 @@ Objects API |docs| -API to manage objects belonging to a certain object type. +API to manage objecttypes and objects. (`Nederlandse versie`_) Developed by `Maykin Media B.V.`_ commissioned by the Municipality of Utrecht. @@ -17,13 +17,9 @@ Developed by `Maykin Media B.V.`_ commissioned by the Municipality of Utrecht. Introduction ============ -The Objects API aims to easily store various objects and make them available in -standardized format. It can be used by any organization to manage -relevant objects. An organization can also choose to use it to -expose objects to the public as *Open Data*. - -To define the format of objects, so called object types, organizations can use -a national and/or local `Objecttypes API`_. +Open Objecten aims to standardize various types of objects in an accessible way and without the need to create a whole new API for +each (simple) object. Instances of these object types can be made available in a standardized format. It can be used by any organization to manage relevant objects. +An organization can also choose to use it to expose objects to the public as *Open Data*. API specification @@ -128,7 +124,7 @@ well tested and available as Docker image. Quickstart ---------- -1. Download and run the Objects API: +1. Download and run Open Objecten: .. code:: bash @@ -163,8 +159,6 @@ Licensed under the EUPL_ .. _`Maykin Media B.V.`: https://www.maykinmedia.nl -.. _`Objecttypes API`: https://github.com/maykinmedia/objecttypes-api - .. _`EUPL`: LICENSE.md .. |build-status| image:: https://github.com/maykinmedia/objects-api/workflows/ci/badge.svg?branch=master diff --git a/SECURITY.rst b/SECURITY.rst index c04314fa..3f4cba69 100644 --- a/SECURITY.rst +++ b/SECURITY.rst @@ -3,65 +3,64 @@ Security policy =============== -The development team is strongly committed to responsible reporting and -disclosure of security-related issues. As such, we’ve adopted and follow a set -of policies which conform to that ideal and are geared toward allowing us to -deliver timely security updates to the official distribution of Objects and -Objecttypes API. +The development team is strongly committed to responsible reporting and +disclosure of security-related issues. As such, we’ve adopted and follow a set +of policies which conform to that ideal and are geared toward allowing us to +deliver timely security updates to the official distribution of Open Objecten. Reporting security issues ------------------------- -**Short version: please report security issues by emailing +**Short version: please report security issues by emailing security@maykinmedia.nl.** -If you discover security issues in Objects or Objecttypes API or related -projects under the same organization, we request you to disclose these in a +If you discover security issues in Open Objecten or related +projects under the same organization, we request you to disclose these in a *responsible* way by mailing to security@maykinmedia.nl. -It is extremely useful if you have a reproducible test case and/or clear steps +It is extremely useful if you have a reproducible test case and/or clear steps on how to reproduce the vulnerability. -Please do not report security issues on the public Github issue tracker, as -this makes it visible which exploits exist before a fix is available, +Please do not report security issues on the public Github issue tracker, as +this makes it visible which exploits exist before a fix is available, potentially comprising a lot of unprotected instances. -Once you’ve submitted an issue via email, you should receive an acknowledgment -from a member of the security team as soon as possible, and depending on the +Once you’ve submitted an issue via email, you should receive an acknowledgment +from a member of the security team as soon as possible, and depending on the action to be taken, you may receive further followup emails. Timeline of the process ----------------------- -Objects and Objecttypes API community support is provided by `Maykin`_. +Open Objecten community support is provided by `Maykin`_. The community support team is responsible for the handling of security issues. -1. The recipients of the report first validate if there is indeed a (possible) +1. The recipients of the report first validate if there is indeed a (possible) issue. 2. After validation, we confirm that we received the report and if it is indeed a valid issue. -3. We have a private Github repository accessible only to the community support - team. In this repository, an issue is created for the vulnerability where +3. We have a private Github repository accessible only to the community support + team. In this repository, an issue is created for the vulnerability where the impact and possible solutions are discussed. -4. The next step is to create a (draft) Github security advisory, which is only - visible to the repository administrators and community support team. +4. The next step is to create a (draft) Github security advisory, which is only + visible to the repository administrators and community support team. Severity and impact will be established here. 5. If appropriate, we request a `CVE identifier`_ from Github. 6. A patch is implemented, reviewed and tested in a private fork. -7. When the fix is tested and release coordination is done, the fix is merged - into the primary repository. The security advisory and release are +7. When the fix is tested and release coordination is done, the fix is merged + into the primary repository. The security advisory and release are published. All managed instances should be updated. -8. The release and security vulnerability are communicated to the community. +8. The release and security vulnerability are communicated to the community. This includes an announcement on `commonground.nl`_. .. _`CVE identifier`: https://cve.mitre.org/cve/identifiers/ .. _`commonground.nl`: https://commonground.nl -.. _`Maykin`: https://www.maykinmedia.nl \ No newline at end of file +.. _`Maykin`: https://www.maykinmedia.nl diff --git a/docs/admin/_assets/img/authentication_objects_add.png b/docs/admin/_assets/img/authentication_objects_add.png index fcfb3409..60fccae5 100644 Binary files a/docs/admin/_assets/img/authentication_objects_add.png and b/docs/admin/_assets/img/authentication_objects_add.png differ diff --git a/docs/admin/_assets/img/authentication_objecttypes_add.png b/docs/admin/_assets/img/authentication_objecttypes_add.png deleted file mode 100644 index dd38ccff..00000000 Binary files a/docs/admin/_assets/img/authentication_objecttypes_add.png and /dev/null differ diff --git a/docs/admin/_assets/img/authentication_objecttypes_main.png b/docs/admin/_assets/img/authentication_objecttypes_main.png deleted file mode 100644 index d252328e..00000000 Binary files a/docs/admin/_assets/img/authentication_objecttypes_main.png and /dev/null differ diff --git a/docs/admin/_assets/img/authorization_objects_objecttype.png b/docs/admin/_assets/img/authorization_objects_objecttype.png index f02e39e5..1f480c9b 100644 Binary files a/docs/admin/_assets/img/authorization_objects_objecttype.png and b/docs/admin/_assets/img/authorization_objects_objecttype.png differ diff --git a/docs/admin/_assets/img/authorization_objects_service.png b/docs/admin/_assets/img/authorization_objects_service.png deleted file mode 100644 index 0be7c256..00000000 Binary files a/docs/admin/_assets/img/authorization_objects_service.png and /dev/null differ diff --git a/docs/admin/authentication.rst b/docs/admin/authentication.rst index 02e61eac..216a5102 100644 --- a/docs/admin/authentication.rst +++ b/docs/admin/authentication.rst @@ -4,53 +4,18 @@ Authentication ============== -Both the Objecttypes API and the Objects API support token authentication (or bearer +Open Objecten supports token authentication (or bearer authentication), which means that everyone who has the security token can access the API. Tokens are configured in the admin. -Objecttypes API -=============== - -In this section we will create a security token for the Objecttypes API and use it in +In this section we will create a security token for Open Objecten and use it in the HTTP request. -.. image:: _assets/img/authentication_objecttypes_main.png - :alt: Click on the "add" button for "Token authorizations" - -In the admin of the Objecttypes API click on the "add" button for "Token authorizations" -resource. - -.. image:: _assets/img/authentication_objecttypes_add.png - :alt: Fill in the form and click on "save" button - -After the form is filled in and submitted the token would be created. The token -itself is a sequence of 40 letters and digits. It's value is generated automatically -when the form is submitted. In this example we will use ``1234`` as a token value. - -Now we can use the created token to request Objecttypes API. The token should be -included into "Authorization" header: ``Authorization: Token 1234`` - -.. code-block:: http - - GET /api/v1/objecttypes HTTP/1.1 - Authorization: Token 1234 - - HTTP/1.1 200 OK - - [] - -If you want to know how to use the Objecttypes API you can follow :ref:`api_usage` - -Objects API -=========== - -The creation of an authentication token for the Objects API is similar as for the -Objecttypes API. .. image:: _assets/img/authentication_objects_main.png :alt: Click on the "add" button for "Token authorizations" -In the admin of the Objects API click on the "add" button for "Token authorizations" +In the admin of the API click on the "add" button for "Token authorizations" resource. .. image:: _assets/img/authentication_objects_add.png @@ -63,18 +28,18 @@ After the form is filled in and submitted the token would be created. The token itself is a sequence of 40 letters and digits. It's value is generated automatically when the form is submitted. In this example we will use ``5678`` as a token value. -Now we can use the created token to request the Objects API. The token should be +Now we can use the created token to request the API. The token should be included into "Authorization" header: ``Authorization: Token 5678`` .. code-block:: http - GET /api/v1/objects HTTP/1.1 + GET /api/v2/objects HTTP/1.1 Authorization: Token 5678 HTTP/1.1 200 OK [] -If you want to know how to use Objects API you can follow :ref:`api_usage` +If you want to know how to use the API you can follow :ref:`api_usage` -Now you can configure :ref:`admin_authorization` for the Objects API. +Now you can configure :ref:`admin_authorization` for the API. diff --git a/docs/admin/authorization.rst b/docs/admin/authorization.rst index d5bb5064..fe4b7103 100644 --- a/docs/admin/authorization.rst +++ b/docs/admin/authorization.rst @@ -8,57 +8,34 @@ While :ref:`admin_authentication` is a process of verifying who a client is, aut is the process of verifying what they have access to. Authorization is usually done after successful authentication. -Objecttypes API -=============== +Objecttypes +=========== -The Objecttypes API doesn't have a particular authorization model, i.e. every +For Objecttypes there is no a particular authorization model, i.e. every authenticated client has access to all object types. -Objects API -=========== +Objects +======= -In the Objects API, clients have explicit access to objects based on their +For Objects, clients have explicit access to objects based on their object types. Permissions for particular object types can be configured in the admin. In the example below we will create a permission to modify tree objects, i.e. objects of "Boom" object type. -Access to Objecttypes API -------------------------- -Since the access to objects is based on their object types, the Objects API should have -credentials to communicate with the Objecttypes API. - -.. image:: _assets/img/authorization_objects_main_service.png - :alt: Click on the "add" button for "Services" - -In the admin page of the Objects API click on the "add" button for "Services" -resource. - -.. image:: _assets/img/authorization_objects_service.png - :alt: Fill in the form and click on "save" button - -Fill in the form with the information about the Objecttypes API and put the Objecttypes API -created in the :ref:`admin_authentication` section of this document into "Header value" field. -If you use NLX you can configure it in the "NLX url" field. After the form is submitted -the Objects API can access the Objecttypes API since it now has a security token for it. - Add an object type ------------------ -Now we can add an object type to the Objects API, to define permissions. +Now we can add an object type to define permissions. .. image:: _assets/img/authorization_objects_main_objecttype.png :alt: Click on the "add" button for "Object type" -In the admin page of the Objects API click on the "add" button for "Object types" +In the admin page click on the "add" button for "Object types" resource. .. image:: _assets/img/authorization_objects_objecttype.png :alt: Fill in the form and click on "save" button -Choose the service created in the previous step and fill in the uuid of the "Boom" object type. -After the form is submitted the object type name will be retrieved automatically from -the Objecttypes API. - Add a permission ---------------- @@ -68,7 +45,7 @@ Finally, it's time to create a permission to access objects with "boom" object t .. image:: _assets/img/authorization_objects_main_permission.png :alt: Click on the "add" button for "Permission" -In the admin page of the Objects API click on the "Add" button for "Permission" +In the admin page click on the "Add" button for "Permission" resource. .. image:: _assets/img/authorization_objects_permission.png @@ -87,16 +64,16 @@ fields you can submit the form. Now the client who has this token can access the objects with the "Boom" object type. -If you want to know how to use Objects API you can follow :ref:`api_usage` +If you want to know how to use the API you can follow :ref:`api_usage` Superuser permissions ---------------------- -It's possible to set up superuser permissions in Objects API. A client with such permissions -is able to request objects for all objecttypes. +It's possible to set up superuser permissions in the API. A client with such permissions +is able to perform any operation on any object or objecttype. -In the admin page of the Objects API go to the "Token authorizations" resource and click on +In the admin page go to the "Token authorizations" resource and click on a token, which should have superuser permissions. Check "is superuser" field. Now this token has read and write permissions for all objects. diff --git a/docs/admin/index.rst b/docs/admin/index.rst index b2236769..00546dc2 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -3,10 +3,10 @@ Admin interface =============== -Both the Objects API and the Objecttypes API have an admin interface that -allows you to configure the APIs and to manage objects and related object types. +Open Objecten has an admin interface that allows you to configure +the API and to manage objects and related object types. -Below, you can find tutorials how to use the admin interface to manage the APIs. +Below, you can find tutorials how to use the admin interface to manage the API. .. toctree:: :maxdepth: 1 diff --git a/docs/admin/notifications.rst b/docs/admin/notifications.rst index 3faa29b0..028be737 100644 --- a/docs/admin/notifications.rst +++ b/docs/admin/notifications.rst @@ -4,8 +4,8 @@ Notifications ============= -The Objects API can be configured to send notifications to a configured Notificaties API. -These notifications are sent whenever Objects are created, updated or deleted via the Objects API. +The API can be configured to send notifications to a configured Notificaties API. +These notifications are sent whenever Objects are created, updated or deleted via the API. Other applications can subscribe to these notifications, for example to trigger certain processes whenever an Object is created. @@ -37,7 +37,7 @@ On the "add service" page, fill in the following information: 1. **Label**: the name of the **Service**, i.e. ``Notificaties API`` 2. **Type**: ``NRC (Notifications`` 3. **Api root url**: the same URL as in the "Notificatiescomponentconfiguratie" -4. **Client ID**: a valid client ID to identify the Objects API (registered in Autorisaties API) +4. **Client ID**: a valid client ID to identify the Open Objecten API (registered in Autorisaties API) 5. **Secret**: a secret corresponding to the client ID (registered in Autorisaties API) 6. **Authorization type**: ``ZGW client_id + secret`` 7. **Header key** / **Header value**: leave empty diff --git a/docs/admin/object.rst b/docs/admin/object.rst index 253444e4..c785d6c7 100644 --- a/docs/admin/object.rst +++ b/docs/admin/object.rst @@ -4,18 +4,17 @@ Objects ======= -Creating and updating objects is usually done using the Objects API. :ref:`api_usage` +Creating and updating objects is usually done using the API. :ref:`api_usage` describes how to do it in detail. But it's also possible to manage objects in the admin interface. In this tutorial we will create and update objects using the Objects admin. -Relate an object type +Create an object type --------------------- -Each object must belong to a particular object type created in the Objecttypes API. +Each object must belong to a particular object type. The access to objects (the authorization) is also based on the related object types. -Therefore before creating the object we need to make the object type from the Objecttypes API -available in the admin interface of the Objects API. The section "Add an object type" of the +Therefore before creating the object we need to make an object type. The section "Add an object type" of the :ref:`admin_authorization` describes how to do it. Create an object @@ -62,7 +61,7 @@ corrected in the "Correction" field of the next record. .. image:: _assets/img/object_create_record.png :alt: Add an object record -In the Objects API you always see one record, which contains data of a certain time (by default +In the API you always see one record for a specific object, which contains data of a certain time (by default the latest one). However in the admin interface you can see all the records created for the object. .. _admin_objects_search: diff --git a/docs/admin/objecttype.rst b/docs/admin/objecttype.rst index 3fa414b9..39e430fb 100644 --- a/docs/admin/objecttype.rst +++ b/docs/admin/objecttype.rst @@ -4,7 +4,7 @@ Object types ============ -Creating and changing object types are common tasks for the Objecttypes API. +Creating and changing object types are common tasks for the API. :ref:`api_usage` describes how to do it with HTTP requests. But you can also use the Objecttypes admin to create, publish and update object types. diff --git a/docs/api/_assets/object-and-objecttypes-quickstart.postman_environment.json b/docs/api/_assets/object-and-objecttypes-quickstart.postman_environment.json deleted file mode 100644 index 6a8de0c6..00000000 --- a/docs/api/_assets/object-and-objecttypes-quickstart.postman_environment.json +++ /dev/null @@ -1,59 +0,0 @@ -{ - "id": "2ce3557f-e857-454a-b924-6323c261a963", - "name": "Objects and Objectttypen (quickstart)", - "values": [ - { - "key": "objecttypes_host", - "value": "http://localhost:8001/", - "enabled": true - }, - { - "key": "objecttypes_token", - "value": "11b2e52852a4b0b853d560d5aa13da32f975db96", - "enabled": true - }, - { - "key": "objecttype_boom_uuid", - "value": "feeaa795-d212-4fa2-bb38-2c34996e5702", - "enabled": true - }, - { - "key": "objecttype_melding_uuid", - "value": "ca754b52-3f37-4c49-837c-130e8149e337", - "enabled": true - }, - { - "key": "objecttype_new", - "value": "", - "enabled": true - }, - { - "key": "objecttype_new_version", - "value": "", - "enabled": true - }, - { - "key": "objects_host", - "value": "http://localhost:8000/", - "enabled": true - }, - { - "key": "objects_token", - "value": "\t0cc593e3e3058af44db02393afe2805b5cdc0ca6", - "enabled": true - }, - { - "key": "object_boom_uuid", - "value": "47454f68-1884-438c-8f69-398f437d59c3", - "enabled": true - }, - { - "key": "object_new", - "value": "", - "enabled": true - } - ], - "_postman_variable_scope": "environment", - "_postman_exported_at": "2020-12-09T12:08:36.063Z", - "_postman_exported_using": "Postman/7.36.0" -} \ No newline at end of file diff --git a/docs/api/_assets/objects-api.postman_collection.json b/docs/api/_assets/objects-api.postman_collection.json deleted file mode 100644 index 353afb40..00000000 --- a/docs/api/_assets/objects-api.postman_collection.json +++ /dev/null @@ -1,332 +0,0 @@ -{ - "info": { - "_postman_id": "f8d9deb4-3e94-4be6-9321-61dfb4bdacf0", - "name": "Objects API", - "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" - }, - "item": [ - { - "name": "Create object \"melding\"", - "event": [ - { - "listen": "test", - "script": { - "id": "6754be53-71c7-4431-a628-2ecf914dea7a", - "exec": [ - "if (pm.response.code === 201) {\r", - " pm.environment.set(\"object_new\", pm.response.json().url);\r", - "}\r", - "" - ], - "type": "text/javascript" - } - } - ], - "request": { - "method": "POST", - "header": [ - { - "key": "Content-Crs", - "value": "EPSG:4326", - "type": "text" - } - ], - "body": { - "mode": "raw", - "raw": "{\n \"type\": \"{{objecttypes_host}}api/v1/objecttypes/{{objecttype_melding_uuid}}\",\n \"record\": {\n \"typeVersion\": 1,\n \"startDate\": \"2020-01-01\",\n \"data\": {\n \"description\": \"Hier is iets ergs aan de hand.\"\n }\n }\n}", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objects_host}}api/v1/objects", - "host": [ - "{{objects_host}}api" - ], - "path": [ - "v1", - "objects" - ] - }, - "description": "This will create a new object of objecttype \"melding\". The URL of the new object will be stored (object_new) to be used by the \"Delete object\" call." - }, - "response": [] - }, - { - "name": "Create object (invalid)", - "request": { - "method": "POST", - "header": [ - { - "key": "Content-Crs", - "value": "EPSG:4326", - "type": "text" - } - ], - "body": { - "mode": "raw", - "raw": "{\n \"type\": \"{{objecttypes_host}}api/v1/objecttypes/{{objecttype_melding_uuid}}\",\n \"record\": {\n \"typeVersion\": 1,\n \"startDate\": \"2020-01-01\",\n \"data\": {\n \t \"tekst\": \"Hier is iets ergs aan de hand.\"\n }\n }\n}", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objects_host}}api/v1/objects", - "host": [ - "{{objects_host}}api" - ], - "path": [ - "v1", - "objects" - ] - } - }, - "response": [] - }, - { - "name": "Create object (no permission)", - "request": { - "method": "POST", - "header": [ - { - "key": "Content-Crs", - "value": "EPSG:4326", - "type": "text" - } - ], - "body": { - "mode": "raw", - "raw": "{\n \"type\": \"{{objecttypes_host}}api/v1/objecttypes/{{objecttype_boom_uuid}}\",\n \"record\": {\n \"typeVersion\": 1,\n \"startDate\": \"2020-01-01\",\n \"data\": {\n \"diameter\": 50,\n \"plantDate\": \"2020-04-12\"\n }\n }\n}", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objects_host}}api/v1/objects", - "host": [ - "{{objects_host}}api" - ], - "path": [ - "v1", - "objects" - ] - } - }, - "response": [] - }, - { - "name": "Retrieve objects", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{objects_host}}api/v1/objects", - "host": [ - "{{objects_host}}api" - ], - "path": [ - "v1", - "objects" - ] - } - }, - "response": [] - }, - { - "name": "Retrieve objects by objecttype \"boom\"", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{objects_host}}api/v1/objects?type={{objecttypes_host}}api/v1/objecttypes/{{objecttype_boom_uuid}}", - "host": [ - "{{objects_host}}api" - ], - "path": [ - "v1", - "objects" - ], - "query": [ - { - "key": "type", - "value": "{{objecttypes_host}}api/v1/objecttypes/{{objecttype_boom_uuid}}" - } - ] - } - }, - "response": [] - }, - { - "name": "Retrieve object \"boom X\"", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{objects_host}}api/v1/objects/{{object_boom_uuid}}", - "host": [ - "{{objects_host}}api" - ], - "path": [ - "v1", - "objects", - "{{object_boom_uuid}}" - ] - } - }, - "response": [] - }, - { - "name": "Retrieve object \"boom X\" on registration date", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{objects_host}}api/v1/objects/{{object_boom_uuid}}?registrationDate=2006-07-12", - "host": [ - "{{objects_host}}api" - ], - "path": [ - "v1", - "objects", - "{{object_boom_uuid}}" - ], - "query": [ - { - "key": "registrationDate", - "value": "2006-07-12" - } - ] - } - }, - "response": [] - }, - { - "name": "Retrieve object \"boom X\" on date", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{objects_host}}api/v1/objects/{{object_boom_uuid}}?date=2006-07-12", - "host": [ - "{{objects_host}}api" - ], - "path": [ - "v1", - "objects", - "{{object_boom_uuid}}" - ], - "query": [ - { - "key": "date", - "value": "2006-07-12" - } - ] - } - }, - "response": [] - }, - { - "name": "Retrieve object history \"boom X\"", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{objects_host}}api/v1/objects/{{object_boom_uuid}}/history", - "host": [ - "{{objects_host}}api" - ], - "path": [ - "v1", - "objects", - "{{object_boom_uuid}}", - "history" - ] - } - }, - "response": [] - }, - { - "name": "Retrieve objects by attribute", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{objects_host}}api/v1/objects?data_attrs=diameter__exact__26", - "host": [ - "{{objects_host}}api" - ], - "path": [ - "v1", - "objects" - ], - "query": [ - { - "key": "data_attrs", - "value": "diameter__exact__26" - } - ] - } - }, - "response": [] - }, - { - "name": "Delete object", - "request": { - "method": "DELETE", - "header": [], - "url": { - "raw": "{{object_new}}", - "host": [ - "{{object_new}}" - ] - }, - "description": "Uses the URL of the newly created object from \"Create object melding\" to delete this object again." - }, - "response": [] - } - ], - "auth": { - "type": "apikey", - "apikey": [ - { - "key": "value", - "value": "Token {{objects_token}}", - "type": "string" - }, - { - "key": "key", - "value": "Authorization", - "type": "string" - } - ] - }, - "event": [ - { - "listen": "prerequest", - "script": { - "id": "ed2fe741-f204-4336-9fb8-80d0f036dfbd", - "type": "text/javascript", - "exec": [ - "" - ] - } - }, - { - "listen": "test", - "script": { - "id": "ea528420-f025-42ac-82c2-cfc28c9ad602", - "type": "text/javascript", - "exec": [ - "" - ] - } - } - ], - "protocolProfileBehavior": {} -} \ No newline at end of file diff --git a/docs/api/_assets/objecttypes-api.postman_collection.json b/docs/api/_assets/objecttypes-api.postman_collection.json deleted file mode 100644 index f2806e7c..00000000 --- a/docs/api/_assets/objecttypes-api.postman_collection.json +++ /dev/null @@ -1,463 +0,0 @@ -{ - "info": { - "_postman_id": "347b5d35-8b3e-46a8-8224-f9b80ff4e80d", - "name": "Objecttypes API", - "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" - }, - "item": [ - { - "name": "Retrieve objecttypes", - "protocolProfileBehavior": { - "disableBodyPruning": true - }, - "request": { - "method": "GET", - "header": [], - "body": { - "mode": "raw", - "raw": "", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objecttypes_host}}api/v1/objecttypes", - "host": [ - "{{objecttypes_host}}api" - ], - "path": [ - "v1", - "objecttypes" - ] - } - }, - "response": [] - }, - { - "name": "Retrieve objecttype \"boom\"", - "protocolProfileBehavior": { - "disableBodyPruning": true - }, - "request": { - "method": "GET", - "header": [], - "body": { - "mode": "raw", - "raw": "", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objecttypes_host}}api/v1/objecttypes/feeaa795-d212-4fa2-bb38-2c34996e5702", - "host": [ - "{{objecttypes_host}}api" - ], - "path": [ - "v1", - "objecttypes", - "feeaa795-d212-4fa2-bb38-2c34996e5702" - ] - } - }, - "response": [] - }, - { - "name": "Retrieve objecttype versions \"boom\"", - "protocolProfileBehavior": { - "disableBodyPruning": true - }, - "request": { - "method": "GET", - "header": [], - "body": { - "mode": "raw", - "raw": "", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objecttypes_host}}api/v1/objecttypes/feeaa795-d212-4fa2-bb38-2c34996e5702/versions", - "host": [ - "{{objecttypes_host}}api" - ], - "path": [ - "v1", - "objecttypes", - "feeaa795-d212-4fa2-bb38-2c34996e5702", - "versions" - ] - } - }, - "response": [] - }, - { - "name": "Retrieve objecttype latest version \"boom\"", - "protocolProfileBehavior": { - "disableBodyPruning": true - }, - "request": { - "method": "GET", - "header": [], - "body": { - "mode": "raw", - "raw": "", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objecttypes_host}}api/v1/objecttypes/feeaa795-d212-4fa2-bb38-2c34996e5702/versions/2", - "host": [ - "{{objecttypes_host}}api" - ], - "path": [ - "v1", - "objecttypes", - "feeaa795-d212-4fa2-bb38-2c34996e5702", - "versions", - "2" - ] - } - }, - "response": [] - }, - { - "name": "Create objecttype \"monument\"", - "event": [ - { - "listen": "test", - "script": { - "id": "0dcbc6f2-698e-49e3-bf65-c293b1cd7eaa", - "exec": [ - "if (pm.response.code === 201) {\r", - " pm.environment.set(\"objecttype_new\", pm.response.json().url);\r", - "}\r", - "" - ], - "type": "text/javascript" - } - } - ], - "request": { - "method": "POST", - "header": [], - "body": { - "mode": "raw", - "raw": "{\n\t\"name\": \"Monument\",\n \"namePlural\": \"Monumenten\",\n \"description\": \"Monumenten in de publieke ruimte.\",\n \"dataClassification\": \"open\"\n}\n", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objecttypes_host}}api/v1/objecttypes", - "host": [ - "{{objecttypes_host}}api" - ], - "path": [ - "v1", - "objecttypes" - ] - }, - "description": "Stores the URL of the newly created objecttype \"monument\" (objecttype_new) so it can be used to create a version of it, and to publish it." - }, - "response": [] - }, - { - "name": "Create object \"monument\"", - "event": [ - { - "listen": "test", - "script": { - "id": "5f5dd3d2-b117-427f-ba6d-85f2c23b5f80", - "exec": [ - "if (pm.response.code === 201) {\r", - " pm.environment.set(\"object_new\", pm.response.json().url);\r", - "}\r", - "" - ], - "type": "text/javascript" - } - } - ], - "request": { - "method": "POST", - "header": [ - { - "key": "Content-Crs", - "type": "text", - "value": "EPSG:4326" - } - ], - "body": { - "mode": "raw", - "raw": "{\n \"type\": \"{{objecttype_new}}\",\n \"record\": {\n \"typeVersion\": 1,\n \"startDate\": \"2020-01-01\",\n \"data\": {\n \"naam\": \"Rembrandtmonument\",\n \"kunstenaarsNaam\": \"Louis Royer\",\n \"description\": \"Het Rembrandtmonument is een 19e-eeuws gedenkteken ter nagedachtenis aan de schilder Rembrandt van Rijn op het Rembrandtplein in Amsterdam.\"\n },\n \"geometry\": {\n \"type\": \"Point\",\n \"coordinates\": [\n 4.896476469311928,\n 52.36651498984676\n ]\n }\n }\n}\n", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objects_host}}api/v1/objects", - "host": [ - "{{objects_host}}api" - ], - "path": [ - "v1", - "objects" - ] - } - }, - "response": [] - }, - { - "name": "Create objecttype (invalid)", - "request": { - "method": "POST", - "header": [], - "body": { - "mode": "raw", - "raw": "{\n\t\"name\": \"monument\",\n \"namePlural\": \"monumenten\",\n \"description\": \"Monumenten in de publieke ruimte.\",\n \"dataClassification\": \"incorrect\"\n}\n", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objecttypes_host}}api/v1/objecttypes", - "host": [ - "{{objecttypes_host}}api" - ], - "path": [ - "v1", - "objecttypes" - ] - } - }, - "response": [] - }, - { - "name": "Create objecttype version", - "event": [ - { - "listen": "test", - "script": { - "id": "1803b6fb-d94e-4120-9504-955483f3993c", - "exec": [ - "if (pm.response.code === 201) {\r", - " pm.environment.set(\"objecttype_new_version\", pm.response.json().url);\r", - "}\r", - "" - ], - "type": "text/javascript" - } - } - ], - "request": { - "method": "POST", - "header": [], - "body": { - "mode": "raw", - "raw": "{\n \"status\": \"draft\",\n \"jsonSchema\": {\n \"title\": \"Monument\",\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"required\": [\"naam\", \"kunstenaarsNaam\"],\n \"properties\": {\n \"naam\": {\n \"type\": \"string\",\n \"description\": \"Naam van het monument die de kunstenaar er aan heeft gegeven.\"\n },\n \"bijschrift\": {\n \"type\": \"string\",\n \"description\": \"Bijschrift die de context van het monument verduidelijkt.\"\n },\n \"kunstenaarsNaam\": {\n \"type\": \"string\",\n \"description\": \"Voor en achternaam van de kunstenaar.\"\n },\n \"kunstenaar\": {\n \"type\": \"string\",\n \"format\": \"url\",\n \"description\": \"URL naar de Natuurlijk Persoon in de BRP.\"\n },\n \"opleverdatum\": {\n \"type\": \"string\",\n \"format\": \"date\",\n \"description\": \"Datum waarop het monument is onthuld.\"\n }\n }\n }\n}\n", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objecttype_new}}/versions", - "host": [ - "{{objecttype_new}}" - ], - "path": [ - "versions" - ] - } - }, - "response": [] - }, - { - "name": "Create objecttype version (invalid)", - "event": [ - { - "listen": "test", - "script": { - "id": "5be7d70e-cdf7-4c89-b4cc-e11d8821a61d", - "exec": [ - "" - ], - "type": "text/javascript" - } - } - ], - "request": { - "method": "POST", - "header": [], - "body": { - "mode": "raw", - "raw": "{\n \"status\": \"draft\",\n \"jsonSchema\": {\n \"title\": \"Monument\",\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"required\": [\"naam\", \"kunstenaarsNaam\"],\n \"properties\": {\n \"bijschrift\": {\n \"type\": \"string\",\n \"description\": \"Bijschrift die de context van het monument verduidelijkt.\"\n },\n \"kunstenaarsNaam\": {\n \"type\": \"string\",\n \"description\": \"Voor en achternaam van de kunstenaar.\"\n },\n \"kunstenaar\": {\n \"type\": \"string\",\n \"format\": \"url\",\n \"description\": \"URL naar de Natuurlijk Persoon in de BRP.\"\n },\n \"opleverdatum\": {\n \"type\": \"string\",\n \"format\": \"date\",\n \"description\": \"Datum waarop het monument is onthuld.\"\n }\n }\n }\n}\n", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objecttype_new}}/versions", - "host": [ - "{{objecttype_new}}" - ], - "path": [ - "versions" - ] - } - }, - "response": [] - }, - { - "name": "Publish objecttype version publish", - "request": { - "method": "PATCH", - "header": [], - "body": { - "mode": "raw", - "raw": "{\n \"status\": \"published\"\n}\n", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objecttype_new_version}}", - "host": [ - "{{objecttype_new_version}}" - ] - } - }, - "response": [] - }, - { - "name": "Delete objecttype version", - "event": [ - { - "listen": "test", - "script": { - "id": "2bd03d17-3723-491e-a236-5c23cad6be77", - "exec": [ - "" - ], - "type": "text/javascript" - } - } - ], - "request": { - "method": "DELETE", - "header": [], - "body": { - "mode": "raw", - "raw": "", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objecttype_new_version}}", - "host": [ - "{{objecttype_new_version}}" - ] - } - }, - "response": [] - }, - { - "name": "Delete objecttype", - "event": [ - { - "listen": "test", - "script": { - "id": "1ad9adb7-9f5d-472e-902e-1c3814520e1b", - "exec": [ - "" - ], - "type": "text/javascript" - } - } - ], - "request": { - "method": "DELETE", - "header": [], - "body": { - "mode": "raw", - "raw": "", - "options": { - "raw": { - "language": "json" - } - } - }, - "url": { - "raw": "{{objecttype_new}}", - "host": [ - "{{objecttype_new}}" - ] - } - }, - "response": [] - } - ], - "auth": { - "type": "apikey", - "apikey": [ - { - "key": "value", - "value": "Token {{objecttypes_token}}", - "type": "string" - }, - { - "key": "key", - "value": "Authorization", - "type": "string" - } - ] - }, - "event": [ - { - "listen": "prerequest", - "script": { - "id": "abaed0ef-f36a-4228-8f33-7aec036cd01e", - "type": "text/javascript", - "exec": [ - "" - ] - } - }, - { - "listen": "test", - "script": { - "id": "aa4b5aef-2420-4b41-8b26-cdd9572c07f3", - "type": "text/javascript", - "exec": [ - "" - ] - } - } - ], - "protocolProfileBehavior": {} -} \ No newline at end of file diff --git a/docs/api/_assets/v1.1.0.pdf b/docs/api/_assets/v1.1.0.pdf deleted file mode 100644 index d8a5ede1..00000000 Binary files a/docs/api/_assets/v1.1.0.pdf and /dev/null differ diff --git a/docs/api/_assets/v1.1.1.pdf b/docs/api/_assets/v1.1.1.pdf deleted file mode 100644 index 2793c256..00000000 Binary files a/docs/api/_assets/v1.1.1.pdf and /dev/null differ diff --git a/docs/api/_assets/v2.0.0-alpha.pdf b/docs/api/_assets/v2.0.0-alpha.pdf deleted file mode 100644 index ca884d7d..00000000 Binary files a/docs/api/_assets/v2.0.0-alpha.pdf and /dev/null differ diff --git a/docs/api/compliancy/api-strategy.rst b/docs/api/compliancy/api-strategy.rst index b47dddb2..8a7cffe2 100644 --- a/docs/api/compliancy/api-strategy.rst +++ b/docs/api/compliancy/api-strategy.rst @@ -4,28 +4,28 @@ API strategy compliancy ======================= -The Objects API and Objecttypes API are designed to adhere to API principles +The Open Objecten API is designed to adhere to API principles defined in `API Designrules`_, which is a part of `Nederlandse API Strategie`_. .. csv-table:: Adherence to API principles - :header: "#", "Principle", "Objects API", "Objecttypes API" - :widths: 10, 40, 25, 25 + :header: "#", "Principle", "Open Objecten API" + :widths: 20, 60, 20 - API-01,Operations are Safe and/or Idempotent,"Yes, with exception of PUT",Yes - API-02,Do not maintain state information at the server,Yes,Yes - API-03,Only apply default HTTP operations,Yes,Yes - API-04,Define interfaces in Dutch unless there is an official English glossary,"No, Objects API has English interface","No, Objecttypes API has English interface" - API-05,Use plural nouns to indicate resources,Yes,Yes - API-06,Create relations of nested resources within the endpoint,"N/a, there are no nested resources",Yes - API-09,Implement custom representation if supported,Yes,No - API-10,Implement operations that do not fit the CRUD model as sub-resources,Yes,Yes - API-16,Use OAS 3.0 for documentation,Yes,Yes - API-17,Publish documentation in Dutch unless there is existing documentation in English or there is an official English glossary available,"No, Objects API has English documentation","No, Objecttypes API has English documentation" - API-18,Include a deprecation schedule when publishing API changes,Yes,Yes - API-19,Allow for a maximum 1 year transition period to a new API version,Yes (6 month),Yes (6 month) - API-20,API-20: Include the major version number only in ihe URI,Yes,Yes - API-48,Leave off trailing slashes from API endpoints,Yes,Yes - API-51,Publish OAS at the base-URI in JSON-format,Yes,Yes + API-01,Operations are Safe and/or Idempotent,"Yes, with exception of PUT" + API-02,Do not maintain state information at the server,Yes + API-03,Only apply default HTTP operations,Yes + API-04,Define interfaces in Dutch unless there is an official English glossary,"No, Open Objecten has English interface" + API-05,Use plural nouns to indicate resources,Yes + API-06,Create relations of nested resources within the endpoint,Yes + API-09,Implement custom representation if supported,No + API-10,Implement operations that do not fit the CRUD model as sub-resources,Yes + API-16,Use OAS 3.0 for documentation,Yes + API-17,Publish documentation in Dutch unless there is existing documentation in English or there is an official English glossary available,"No, Open Objecten API has English documentation" + API-18,Include a deprecation schedule when publishing API changes,Yes + API-19,Allow for a maximum 1 year transition period to a new API version,Yes (6 month) + API-20,API-20: Include the major version number only in the URI,Yes + API-48,Leave off trailing slashes from API endpoints,Yes + API-51,Publish OAS at the base-URI in JSON-format,Yes .. _`API Designrules`: https://docs.geostandaarden.nl/api/API-Designrules/ diff --git a/docs/api/compliancy/vng.rst b/docs/api/compliancy/vng.rst index ad8b6906..bb4dc593 100644 --- a/docs/api/compliancy/vng.rst +++ b/docs/api/compliancy/vng.rst @@ -4,7 +4,7 @@ VNG compliancy ============== -The Objects and Objecttypes API specifications are proposed by the `municipality +The API specifications are proposed by the `municipality of Utrecht`_ and submitted to the `VNG`_ for to become a Dutch national standard. The VNG (Vereniging van Nederlandse Gemeenten) is the Association of Dutch Municipalities. diff --git a/docs/api/index.rst b/docs/api/index.rst index 4ac1c6b7..420e9604 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -4,27 +4,17 @@ API-specifications ================== -The Objects API and Objecttypes API are scheduled to be a `recommended standard -as of March 1, 2022`_. Their specifications can be found below. - ====================== ========================================== API Specification version(s) ====================== ========================================== -`Objecttypes API`_ 2.2.2 ( - `Redoc `__, - `Swagger `__ - ) -`Objects API`_ 2.6.0 ( +`Open Objecten`_ 2.6.0 ( `Redoc `__, - `Swagger `__ - ) + `Swagger `__) ====================== ========================================== See their respective repositories for the latest and previous versions. -.. _`recommended standard as of March 1, 2022`: https://commonground.nl/news/view/0d7ff0a6-e960-412b-9a83-33bb1810c67d/twee-nieuwe-standaardverklaringen-deze-apis-maken-het-samenwerken-makkelijker-in-2022 -.. _`Objecttypes API`: https://github.com/maykinmedia/objecttypes-api -.. _`Objects API`: https://github.com/maykinmedia/objects-api +.. _`Open Objecten`: https://github.com/maykinmedia/objects-api .. toctree:: @@ -32,7 +22,5 @@ See their respective repositories for the latest and previous versions. :caption: Further reading usage - postman - performance compliancy/api-strategy compliancy/vng diff --git a/docs/api/performance.rst b/docs/api/performance.rst deleted file mode 100644 index 77be4075..00000000 --- a/docs/api/performance.rst +++ /dev/null @@ -1,47 +0,0 @@ -=================== -Performance -=================== - -To ensure good user experience and quality of performance, we have a dedicated `performance testing repository`_. It runs on a system with the following specifications: - -.. csv-table:: System specifications - :widths: 20, 80 - :delim: : - - **Operating System**: Debian GNU/Linux 10 (buster) [x86_64 GNU/Linux] - **RAM**: 4GB - **CPU(s)**: x2 (Intel Xeon E312xx) - **Hard drive**: 52GB - -The tests run under the following conditions: - -* 500 total objects are used to ensure compatibility across older versions without pagination. -* 4 unique objecttypes. -* A single user simulates requests for a duration of 5 minutes. - -We run the tests after every major version of the Objects API. -After that, we report and document the stats. This careful analysis allows us to showcase our high-quality optimization process. - -Results -_______ - - -.. csv-table:: Performance results per version (30 minutes) - :header: "Method"; "Test"; "v2.0.0-alpha"; "v1.1.1"; "v1.1.0" - :delim: ; - - GET;Retrieve all objects (ms);127;127;125 - GET;Retrieve by data_attrs (ms);117;111;115 - GET;Retrieve by date (ms);129;128;127 - GET;Retrieve by geo coordinates (ms);127;128;127 - GET;Retrieve by registrationDate (ms);130;131;130 - GET;Retrieve by single object (ms);106;106;109 - ;Aggregated;**123**;**122**;**122** - -All performance reports are available for download for all versions: - -- :download:`v2.0.0-alpha <_assets/v2.0.0-alpha.pdf>` -- :download:`v1.1.1 <_assets/v1.1.1.pdf>` -- :download:`v1.1.0 <_assets/v1.1.0.pdf>` - -.. _`performance testing repository`: https://github.com/maykinmedia/objects-api-performance diff --git a/docs/api/postman.rst b/docs/api/postman.rst deleted file mode 100644 index 5cd6c758..00000000 --- a/docs/api/postman.rst +++ /dev/null @@ -1,26 +0,0 @@ -=================== -Postman collections -=================== - -To play around with the APIs we constructed `Postman`_ collections that work -with the demo data supplied with the :ref:`installation_quickstart`. - -These Postman collections are a set of pre-constructed API-calls to access the -most commonly used resources and query parameters. The configuration matches -the :ref:`installation_quickstart` configuration but can be changed to match -your own setup. - -To import the collection into Postman, follow the next steps: - -#. Open the Postman application. -#. At the top left, click on ``File -> Import``, or CTRL+O. -#. Drag the file or browse using ``Upload Files`` button. -#. Click ``Import``. - -* :download:`Objects API<_assets/objects-api.postman_collection.json>` -* :download:`Objecttypes API<_assets/objecttypes-api.postman_collection.json>` -* :download:`Object and Objecttypes configuration (quickstart)<_assets/object-and-objecttypes-quickstart.postman_environment.json>` - -.. _`Postman`: https://www.postman.com/downloads/ - - diff --git a/docs/api/usage.rst b/docs/api/usage.rst index 9528ccdc..44dc5066 100644 --- a/docs/api/usage.rst +++ b/docs/api/usage.rst @@ -7,11 +7,11 @@ API Usage In this section, we'll show how to get started with your first object type, and create an object for this object type. -Objecttypes API -=============== -Before continuing, make sure you have an API token to access the Objecttypes API. +Objecttypes +=========== +Before continuing, make sure you have an API token. :ref:`admin_authentication` document describes how to do it in details. -In the examples below we use the API token for the Objecttypes API with the value ``1234``. +In the examples below we use the API token with the value ``1234``. Let's start with creating an object type. For example, you want to store data about trees (Bomen) in your town. First, you need to decide which attributes your data @@ -76,16 +76,16 @@ Create an object type Now we need to create an object type which will include this JSON schema. The object type consists of metadata of the object type and (a version of) the JSON schema. This separation -exists because the Objecttypes API supports versioning of the JSON schemas. If you want to change the +exists because the API supports versioning of the JSON schemas. If you want to change the JSON schema in the objecttype, a new version will be created. Therefore you don't need to worry -that a new version of the Object type schema would not match the exising objects in Objects API since +that a new version of the Object type schema would not match the exising objects since these objects refer to the previous version. So let's create the object type metadata: .. code-block:: http - POST /api/v1/objecttypes HTTP/1.1 + POST /api/v2/objecttypes HTTP/1.1 Authorization: Token 1234 { @@ -111,7 +111,7 @@ a list of versions of the JSON schema, which is initially empty. HTTP/1.1 201 Created { - "url": "http:///api/v1/objecttypes/", + "url": "http:///api/v2/objecttypes/", "name": "boom", "namePlural": "bomen", "description": "Bomen in de publieke ruimte.", @@ -134,7 +134,7 @@ Now we can add our JSON schema to the created object type as its version: .. code-block:: http - POST /api/v1/objecttypes//versions HTTP/1.1 + POST /api/v2/objecttypes//versions HTTP/1.1 Authorization: Token 1234 { @@ -153,9 +153,9 @@ The response contains the url of the created version of the object type. HTTP/1.1 201 OK { - "url": "http:///api/v1/objecttypes//versions/1", + "url": "http:///api/v2/objecttypes//versions/1", "version": 1, - "objectType": "http:///api/v1/objecttypes/", + "objectType": "http:///api/v2/objecttypes/", "status": "draft", "jsonSchema": { "$schema": "http://json-schema.org/draft-07/schema", @@ -174,12 +174,12 @@ it anymore, unless you create a new version. Publish an object type version ------------------------------ -Let's publish our object type version. In the Objecttypes API you can do it with a +Let's publish our object type version. In the API you can do it with a PATCH request: .. code-block:: http - PATCH /api/v1/objecttypes//versions/1 HTTP/1.1 + PATCH /api/v2/objecttypes//versions/1 HTTP/1.1 Authorization: Token 1234 { @@ -193,9 +193,9 @@ In the response you can see that ``publishedAt`` attribute now contains the curr HTTP/1.1 200 OK { - "url": "http:///api/v1/objecttypes//versions/1", + "url": "http:///api/v2/objecttypes//versions/1", "version": 1, - "objectType": "http:///api/v1/objecttypes/", + "objectType": "http:///api/v2/objecttypes/", "status": "published", "jsonSchema": { "$schema": "http://json-schema.org/draft-07/schema", @@ -213,7 +213,7 @@ For example: .. code-block:: http - PATCH /api/v1/objecttypes//versions/1 HTTP/1.1 + PATCH /api/v2/objecttypes//versions/1 HTTP/1.1 Authorization: Token 1234 { @@ -245,13 +245,13 @@ Once the object type is created it can always be retrieved by its url: .. code-block:: http - GET /api/v1/objecttypes/ HTTP/1.1 + GET /api/v2/objecttypes/ HTTP/1.1 Authorization: Token 1234 HTTP/1.1 200 OK { - "url": "http:///api/v1/objecttypes/", + "url": "http:///api/v2/objecttypes/", "name": "boom", "namePlural": "bomen", "description": "Bomen in de publieke ruimte.", @@ -268,7 +268,7 @@ Once the object type is created it can always be retrieved by its url: "createdAt": "2021-03-03", "modifiedAt": "2021-03-03", "versions": [ - "http:///api/v1/objecttypes//versions/1" + "http:///api/v2/objecttypes//versions/1" ] } @@ -276,19 +276,18 @@ You can see that ``versions`` attribute includes a list of urls to all the versi object type. -Objects API -=========== +Objects +======= Now we have an object type containing a JSON schema for tree objects and we are ready to create objects. Before going further please, make sure that you configured the proper authentication and authorizations in the admin: -* The Objects API can access the Objecttypes API -* The API token (in the Objects API) has write permissions for the object type "Boom". +* The API token has write permissions for the object type "Boom". :ref:`admin_authentication` and :ref:`admin_authorization` document how to do it in details. -In the examples below we use the API token for the Objects API with the value ``5678``. +In the examples below we use the API token with the value ``5678``. Create an object ---------------- @@ -313,12 +312,12 @@ system you are using. .. code-block:: http - POST /api/v1/objects HTTP/1.1 + POST /api/v2/objects HTTP/1.1 Authorization: Token 5678 Content-Crs: EPSG:4326 { - "type": "http:///api/v1/objecttypes/", + "type": "http:///api/v2/objecttypes/", "record": { "typeVersion": 1, "startAt": "2021-01-01", @@ -344,8 +343,8 @@ initial version. The response contains the URL of the object: HTTP/1.1 201 Created { - "url": "http:///api/v1/objects/", - "type": "http:///api/v1/objecttypes/", + "url": "http:///api/v2/objects/", + "type": "http:///api/v2/objecttypes/", "record": { "index": 1, "typeVersion": 1, @@ -378,12 +377,12 @@ For example, let's try to create the following object: .. code-block:: http - POST /api/v1/objects HTTP/1.1 + POST /api/v2/objects HTTP/1.1 Authorization: Token 5678 Content-Crs: EPSG:4326 { - "type": "http:///api/v1/objecttypes/", + "type": "http:///api/v2/objecttypes/", "record": { "typeVersion": 1, "startAt": "2021-03-03", @@ -416,14 +415,14 @@ Once the object is created, it can always be retrieved by its URL: .. code-block:: http - GET /api/v1/objects/ HTTP/1.1 + GET /api/v2/objects/ HTTP/1.1 Authorization: Token 5678 HTTP/1.1 200 OK { - "url": "http:///api/v1/objects/", - "type": "http:///api/v1/objecttypes/", + "url": "http:///api/v2/objects/", + "type": "http:///api/v2/objecttypes/", "record": { "index": 1, "typeVersion": 1, @@ -451,7 +450,7 @@ Once the object is created, it can always be retrieved by its URL: Retrieve objects of certain object type --------------------------------------- -The Objects API supports different filter and search options. +The API supports different filter and search options. You can filter objects by: * object type @@ -462,15 +461,15 @@ To filter the list by a particular object type you can use the ``type`` query pa .. code-block:: http - GET /api/v1/objects?type=http:///api/v1/objecttypes/ HTTP/1.1 + GET /api/v2/objects?type=http:///api/v2/objecttypes/ HTTP/1.1 Authorization: Token 5678 HTTP/1.1 200 OK [ { - "url": "http:///api/v1/objects/", - "type": "http:///api/v1/objecttypes/", + "url": "http:///api/v2/objects/", + "type": "http:///api/v2/objecttypes/", "record": { "index": 1, "typeVersion": 1, @@ -498,12 +497,12 @@ To filter the list by a particular object type you can use the ``type`` query pa Retrieve the history of an object --------------------------------- -The Objects API supports versioning, i.e. when an object is updated, its previous states +The API supports versioning, i.e. when an object is updated, its previous states can also be retrieved. In the API these are called ``records``. .. code-block:: http - GET /api/v1/objects//history HTTP/1.1 + GET /api/v2/objects//history HTTP/1.1 Authorization: Token 5678 HTTP/1.1 200 OK @@ -540,7 +539,7 @@ Retrieve an object (record) for a particular date ------------------------------------------------- Since there could be a difference between the real date of -the object change and its registration in the system, the Objects API support both +the object change and its registration in the system, the API support both material and formal history. The material history describes the history as it should be (stored in the ``startAt`` and ``endAt`` attributes). The formal history describes the history as it was administratively processed (stored in the ``registeredAt`` @@ -554,15 +553,15 @@ First, let's do it from the material history perspective: .. code-block:: http - GET /api/v1/objects?date=2021-02-02 HTTP/1.1 + GET /api/v2/objects?date=2021-02-02 HTTP/1.1 Authorization: Token 5678 HTTP/1.1 200 OK [ { - "url": "http:///api/v1/objects/", - "type": "http:///api/v1/objecttypes/", + "url": "http:///api/v2/objects/", + "type": "http:///api/v2/objecttypes/", "record": { "index": 1, "typeVersion": 1, @@ -595,7 +594,7 @@ Now let's do the same but from a formal history perspective: .. code-block:: http - GET /api/v1/objects?registrationDate=2021-02-02 HTTP/1.1 + GET /api/v2/objects?registrationDate=2021-02-02 HTTP/1.1 Authorization: Token 5678 HTTP/1.1 200 OK @@ -603,4 +602,4 @@ Now let's do the same but from a formal history perspective: [] Our tree object was created at 2021-03-03 (``registrationAt``), so it didn't exist -(administratively speaking) at 2021-02-02 yet. Hence, the Objects API response is an empty list. +(administratively speaking) at 2021-02-02 yet. Hence, the response is an empty list. diff --git a/docs/index.rst b/docs/index.rst index 641f2e2d..e0b5a76e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,16 +1,13 @@ Documentation ============= -The :ref:`Objects API` and the Objecttypes API are two components that complement -each other. The :ref:`Objecttypes API` holds the object definitions for objects that -can be stored in the Objects API. Together they provide a powerful way to -create and store any kind of object. +The Open Objecten API consists of two main resources: :ref:`Objecttypes` & :ref:`Objects`. +Objecttypes contains the object definitions and Objects the instances of these Objecttypes. Designed in line with the `Common Ground`_ model, they can be used by other APIs that need to store object specific data. -Both the Objects API and the Objecttypes API are and only use -:ref:`introduction_open-source`. +Open Objecten is and only uses :ref:`introduction_open-source`. .. _`Common Ground`: https://commonground.nl/ @@ -25,33 +22,24 @@ To get you started, you might find some of these links relevant: * Want to know how the admin interface works? Go to the :ref:`admin_index` -.. _Objecttypes API: +.. _Objecttypes: -Objecttypes API ---------------- +Objecttypes +----------- Standardize various types of objects in an accessible way and without the need to create a whole new API for each (simple) object. -This national level API is required for registering objects in local -:ref:`Objects APIs`. Organizations can also run the API locally, to use -both national and local definitions of objects. - +.. _Objects: -.. _Objects API: -.. _Objects APIs: - -Objects API ------------ +Objects +------- Easily store and expose various objects and make them available in a standardized format. It can be used by any organization to manage relevant objects. An organization can also choose to use it to expose objects to the public as *Open Data*. -To define the format of objects, organizations can use -a national and/or local :ref:`Objecttypes API`. - .. toctree:: :maxdepth: 2 @@ -63,4 +51,4 @@ a national and/or local :ref:`Objecttypes API`. installation/index manual/index examples/index - changelog \ No newline at end of file + changelog diff --git a/docs/installation/config.rst b/docs/installation/config.rst index 75cf37b6..74ec4c37 100644 --- a/docs/installation/config.rst +++ b/docs/installation/config.rst @@ -5,7 +5,7 @@ Environment configuration reference =================================== -The Objects and Objecttypes APIs can be run both as a Docker container or a VPS / dedicated server. +Open Objecten can be run as a Docker container or a VPS / dedicated server. It relies on other services, such as database and cache backends, which can be configured through environment variables. @@ -133,10 +133,10 @@ Optional Initial superuser creation (Docker only) ---------------------------------------- -A clean installation of Objects API comes without pre-installed or pre-configured admin +A clean installation of Open Objecten comes without pre-installed or pre-configured admin user by default. -Users of Objects API can opt-in to provision an initial superuser via environment +Users can opt-in to provision an initial superuser via environment variables. The user will only be created if it doesn't exist yet. * ``OBJECTS_SUPERUSER_USERNAME``: specify the username of the superuser to create. Setting @@ -150,7 +150,7 @@ variables. The user will only be created if it doesn't exist yet. Initial configuration --------------------- -Both Objects API and Objecttypes API support `setup_configuration` management command, +Open Objecten supports the `setup_configuration` management command, which allows configuration via environment variables. All these environment variables are described at :ref:`command line `. diff --git a/docs/installation/config_cli.rst b/docs/installation/config_cli.rst index b7465c12..21fd7bd0 100644 --- a/docs/installation/config_cli.rst +++ b/docs/installation/config_cli.rst @@ -6,72 +6,3 @@ Configuration (CLI) =================== .. setup-config-usage:: - :show_command_usage: true - :show_steps: false - :show_steps_toc: false - :show_steps_autodoc: false - -Objects API -=========== - -.. setup-config-usage:: - :show_command_usage: false - -Objecttypes API -=============== - -.. FIXME these can currently only be included manually, because these docs are built in -.. the objects API repo - -.. autoclass:: django_setup_configuration.contrib.sites.steps.SitesConfigurationStep - :noindex: -.. setup-config-example:: django_setup_configuration.contrib.sites.steps.SitesConfigurationStep - -.. autoclass:: mozilla_django_oidc_db.setup_configuration.steps.AdminOIDCConfigurationStep - :noindex: -.. setup-config-example:: mozilla_django_oidc_db.setup_configuration.steps.AdminOIDCConfigurationStep - - -**objecttypes.setup_configuration.steps.token_auth.TokenAuthConfigurationStep** -------------------------------------------------------------------------------- - -Configure tokens with permissions for other applications to access Objectstypes API - -.. code-block:: yaml - - tokenauth_config_enable: true - tokenauth: - - # REQUIRED: true - items: - - - - # DESCRIPTION: A human-friendly label to refer to this token - # REQUIRED: true - identifier: objects-api - - # REQUIRED: true - token: modify-this - - # DESCRIPTION: Name of the person in the organization who can access the API - # REQUIRED: true - contact_person: example_string - - # DESCRIPTION: Email of the person, who can access the API - # REQUIRED: true - email: example_string - - # DESCRIPTION: Organization which has access to the API - # DEFAULT VALUE: "" - # REQUIRED: false - organization: example_string - - # DESCRIPTION: Application which has access to the API - # DEFAULT VALUE: "" - # REQUIRED: false - application: example_string - - # DESCRIPTION: Administration which has access to the API - # DEFAULT VALUE: "" - # REQUIRED: false - administration: example_string diff --git a/docs/installation/deployment/index.rst b/docs/installation/deployment/index.rst index e5d315ba..e4c05318 100644 --- a/docs/installation/deployment/index.rst +++ b/docs/installation/deployment/index.rst @@ -3,17 +3,16 @@ Deployment ========== -Both (*Objects* and *Objecttypes*) APIs are containerized applications and can be +Open Objecten is an containerized application and can be deployed to a `Kubernetes`_ cluster using a `Helm`_ chart. The documentation includes installation process and the reference configuration. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Deployment - objects-api/index - objecttypes-api/index + kubernetes .. _`Helm`: https://helm.sh/ diff --git a/docs/installation/deployment/objects-api/kubernetes.rst b/docs/installation/deployment/kubernetes.rst similarity index 89% rename from docs/installation/deployment/objects-api/kubernetes.rst rename to docs/installation/deployment/kubernetes.rst index e7756d0e..8e48723a 100644 --- a/docs/installation/deployment/objects-api/kubernetes.rst +++ b/docs/installation/deployment/kubernetes.rst @@ -4,10 +4,10 @@ Kubernetes ========== -Here you can find a reference implementation of the Objects API deployment for +Here you can find a reference implementation of the Open Objecten deployment for a Kubernetes cluster using `Helm`_. -The `Helm chart`_ installs the Objects API and is dependent on a PostgreSQL +The `Helm chart`_ installs Open Objecten and is dependent on a PostgreSQL database, installed using a `subchart`_. .. warning:: The default settings are unsafe and should only be used for @@ -47,4 +47,4 @@ of the application: .. _`Helm`: https://helm.sh/ .. _`subchart`: https://github.com/bitnami/charts/tree/master/bitnami/postgresql -.. _`Helm chart`: https://github.com/maykinmedia/charts/tree/main/charts/objecten \ No newline at end of file +.. _`Helm chart`: https://github.com/maykinmedia/charts/tree/main/charts/objecten diff --git a/docs/installation/deployment/objects-api/index.rst b/docs/installation/deployment/objects-api/index.rst deleted file mode 100644 index 79d4701b..00000000 --- a/docs/installation/deployment/objects-api/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _deployment_objects_index: - -====================== -Objects API deployment -====================== - -.. toctree:: - :maxdepth: 1 - - kubernetes diff --git a/docs/installation/deployment/objecttypes-api/index.rst b/docs/installation/deployment/objecttypes-api/index.rst deleted file mode 100644 index 69b5714f..00000000 --- a/docs/installation/deployment/objecttypes-api/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _deployment_objecttypes_index: - -========================== -Objecttypes API deployment -========================== - -.. toctree:: - :maxdepth: 1 - - kubernetes diff --git a/docs/installation/deployment/objecttypes-api/kubernetes.rst b/docs/installation/deployment/objecttypes-api/kubernetes.rst deleted file mode 100644 index f4f9e34a..00000000 --- a/docs/installation/deployment/objecttypes-api/kubernetes.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _deployment_objecttypes_kubernetes: - -========== -Kubernetes -========== - -Here you can find a reference implementation of the Objecttypes API deployment for -a Kubernetes cluster using `Helm`_. - -The `Helm chart`_ installs the Objecttypes API and is dependent on a PostgreSQL -database, installed using a `subchart`_. - -.. warning:: The default settings are unsafe and should only be used for - development purposes. Configure proper secrets, enable persistence, add - certificates before using in production. - - -Installation -============ - -Install the Helm chart with following commands: - -.. code:: shell - - helm repo add maykinmedia https://maykinmedia.github.io/charts/ - helm search repo maykinmedia - helm install my-release maykinmedia/objecttypen - - -Use Kubernetes CLI to monitor the status of deployment: - -.. code:: shell - - kubectl get pods - - -If the Ingress is not configured you can use `port-forward` to check the status -of the application: - -.. code:: shell - - export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=objecttypes,app.kubernetes.io/instance=objecttypes" -o jsonpath="{.items[0].metadata.name}") - export CONTAINER_PORT=$(kubectl get pod --namespace default $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}") - echo "Visit http://127.0.0.1:8080 to use your application" - kubectl --namespace default port-forward $POD_NAME 8080:$CONTAINER_PORT - -.. _`Helm`: https://helm.sh/ -.. _`subchart`: https://github.com/bitnami/charts/tree/master/bitnami/postgresql -.. _`Helm chart`: https://github.com/maykinmedia/charts/tree/main/charts/objecttypen \ No newline at end of file diff --git a/docs/installation/hardware.rst b/docs/installation/hardware.rst index 6fbeb6da..fcfc5480 100644 --- a/docs/installation/hardware.rst +++ b/docs/installation/hardware.rst @@ -79,7 +79,7 @@ several instances. Postgresql database minimum requirements ---------------------------------------- -The performance of Objects API under load is very much dependant on the performance of the Postgresql database. The number of requests per second and the total number of objects may affect the duration of the API calls. In order to avoid performance issues in production and aid in resolving performance issues we recommend to optimize the resources available and fine-tune the Postgresql with the help of `pgbench`. This built-in Postgresql tool gives an indication of the performance of the database setup. +The performance of the Open Objecten API under load is very much dependant on the performance of the Postgresql database. The number of requests per second and the total number of objects may affect the duration of the API calls. In order to avoid performance issues in production and aid in resolving performance issues we recommend to optimize the resources available and fine-tune the Postgresql with the help of `pgbench`. This built-in Postgresql tool gives an indication of the performance of the database setup. An example run using `pgbench`:: @@ -115,4 +115,4 @@ Kubernetes recommendations * Preferably use 2 load balancer (like Traefik) replica's. * Use as many replica's as available CPU's taking into account you need to have a few - replica's for your load balancer, and possibly other services. \ No newline at end of file + replica's for your load balancer, and possibly other services. diff --git a/docs/installation/index.rst b/docs/installation/index.rst index a26f7668..3744db16 100644 --- a/docs/installation/index.rst +++ b/docs/installation/index.rst @@ -4,8 +4,8 @@ Installation ============ In addition to making its source code available publicly, the reference -implementation for the Objects API and Objecttypes API are also maintained and -work out-of-the-box for most use cases. +implementation for Open Objecten is also maintained and +works out-of-the-box for most use cases. For the sake of simplicity, we have chosen to use Docker and Docker Compose for this. diff --git a/docs/installation/observability/index.rst b/docs/installation/observability/index.rst index 798015b3..f449d2bc 100644 --- a/docs/installation/observability/index.rst +++ b/docs/installation/observability/index.rst @@ -13,9 +13,9 @@ Tracing, which provide insight in: * performance of the system * how the system is used -Objects API operates in distributed environments, and being able to fully trace a +Open Objecten operates in distributed environments, and being able to fully trace a customer request from start to end, observability tools are crucial. Below we provide -some additional context for infastructure teams that wish to integrate Objects API in +some additional context for infastructure teams that wish to integrate Open Objecten in their observability stack. .. toctree:: diff --git a/docs/installation/observability/logging.rst b/docs/installation/observability/logging.rst index ca394ead..8bfdd452 100644 --- a/docs/installation/observability/logging.rst +++ b/docs/installation/observability/logging.rst @@ -6,13 +6,13 @@ Logging Logging is the practice of emitting log messages that describe what is happening in the system, or "events" in short. Log events can have varying degrees of severity, such as -``debug``, ``info``, ``warning``, ``error`` or even ``critical``. By default, Objects API +``debug``, ``info``, ``warning``, ``error`` or even ``critical``. By default, Open Objecten emits logs with level ``info`` and higher. A collection of log events with a correlation ID (like a request or trace ID) allow one to reconstruct the chain of events that took place which lead to a particular outcome. -Objects API emits structured logs in JSON format (unless explicitly configured otherwise), +Open Objecten emits structured logs in JSON format (unless explicitly configured otherwise), which should make log aggregation and analysis easier. We try to keep a consistent log message structure, where the following keys @@ -40,7 +40,7 @@ Other keys that frequently occur are: ``request_id`` Present for application logs emitted during an HTTP request, makes it possible to correlate multiple log entries for a single request. Not available in logs emitted - by background tasks or logs emitted before/after the Objects API app. + by background tasks or logs emitted before/after the Open Objecten app. .. tip:: Certain log aggregation solutions require you to configure "labels" to extract for efficient querying. You can use the above summary of log context keys to configure @@ -59,7 +59,7 @@ Logging Format Objects -------------- -Objects API emits structured logs (using `structlog `_). +Open Objecten emits structured logs (using `structlog `_). A log line can be formatted like this: .. code-block:: json @@ -78,27 +78,6 @@ A log line can be formatted like this: "level":"info" } -Format Objecttypes ------------------- - -Objecttypes API emits structured logs (using `structlog `_). -A log line can be formatted like this: - -.. code-block:: json - - { - "uuid":"b427ef84-189d-43aa-9efd-7bb2c459e281", - "naam":"test" - "token_identifier":"application-test", - "token_application":"Application (test)", - "event":"objecttype_created", - "user_id":null, - "request_id":"2f9e9a5b-d549-4faa-a411-594aa8a52eee", - "timestamp":"2025-05-19T14:09:20.339166Z", - "logger":"objecttypes.api.v2.views", - "level":"info" - } - Each log line will contain an ``event`` type, a ``timestamp`` and a ``level``. Dependent on your configured ``LOG_LEVEL`` (see :ref:`installation_env_config` for more information), only log lines with of that level or higher will be emitted. @@ -106,20 +85,18 @@ only log lines with of that level or higher will be emitted. API log events -------------- -Below is the list of logging ``event`` types that Objects and Objecttypes API can emit. In addition to the mentioned +Below is the list of logging ``event`` types that the API can emit. In addition to the mentioned context variables, these events will also have the **request bound metadata** described in the :ref:`django-structlog documentation `. -Objects API -~~~~~~~~~~~ +Objects +~~~~~~~ -* ``objecttypes_api_request_failure``: a request to the Objecttypes API has failed. Additional context: ``exc_info``. -* ``search_failed_for_datastore``: attempted to perform ``jsonpath`` search for a backend that does not support this operation. Additional context: ``exc_info``. * ``object_created``: created an ``Object`` via the API. Additional context: ``object_uuid``, ``objecttype_uuid``, ``objecttype_version``, ``token_identifier``, ``token_application``. * ``object_updated``: updated an ``Object`` via the API. Additional context: ``object_uuid``, ``objecttype_uuid``, ``objecttype_version``, ``token_identifier``, ``token_application``. * ``deprecated_endpoint_called``: a deprecated endpoint was called. Additional context: ``endpoint``. -Objecttypes API -~~~~~~~~~~~~~~~ +Objecttypes +~~~~~~~~~~~ * ``objecttype_created``: created an ``Objecttype`` via the API. Additional context: ``uuid``, ``naam``, ``token_identifier``, ``token_application``. * ``objecttype_updated``: updated an ``Objecttype`` via the API. Additional context: ``uuid``, ``naam``, ``token_identifier``, ``token_application``. diff --git a/docs/installation/observability/metrics.rst b/docs/installation/observability/metrics.rst index c94df222..7e8eecfd 100644 --- a/docs/installation/observability/metrics.rst +++ b/docs/installation/observability/metrics.rst @@ -4,7 +4,7 @@ Metrics ======= -Objects API produces application metrics (using Open Telemetry). +Open Objecten API produces application metrics (using Open Telemetry). .. note:: The exact metric names that show up may be transformed, e.g. Prometheus replaces periods with underscores, and processing pipelines may add prefixes or suffixes. @@ -24,7 +24,7 @@ Objects API produces application metrics (using Open Telemetry). .. code-block:: promql - avg by (type) (otel_objects_auth_user_count{scope="global"}) + avg by (type) (otel_openobjecten_auth_user_count{scope="global"}) Generic ======= @@ -43,7 +43,7 @@ Application specific Accounts -------- -``objects.auth.user_count`` +``openobjecten.auth.user_count`` Reports the number of users in the database. This is a global metric, you must take care in de-duplicating results. Additional attributes are: @@ -55,18 +55,18 @@ Accounts .. code-block:: promql max by (type) (last_over_time( - otel_objects_auth_user_count{scope="global"} + otel_openobjecten_auth_user_count{scope="global"} [1m] )) -``objects.auth.login_failures`` +``openobjecten.auth.login_failures`` A counter incremented every time a user login fails (typically because of invalid credentials). Does not include the second factor, if enabled. Additional attributes: - ``http_target`` - the request path where the login failure occurred, if this happened in a request context. -``objects.auth.user_lockouts`` +``openobjecten.auth.user_lockouts`` A counter incremented every time a user is locked out because they reached the maximum number of failed attempts. Additional attributes: @@ -74,14 +74,14 @@ Accounts happened in a request context. - ``username`` - username of the user trying to log in. -``objects.auth.logins`` +``openobjecten.auth.logins`` Counter incrementing on every successful login by a user. Additional attributes: - ``http_target`` - the request path where the login failure occurred, if this happened in a request context. - ``username`` - username of the user trying to log in. -``objects.auth.logouts`` +``openobjecten.auth.logouts`` Counter incrementing every time a user logs out. Additional attributes: - ``username`` - username of the user who logged out. @@ -89,20 +89,32 @@ Accounts Objects ------- -``objects.object.creates`` +``openobjecten.object.creates`` Reports the number of objects created via the API. -``objects.object.updates`` +``openobjecten.object.updates`` Reports the number of objects updated via the API. -``objects.object.deletes`` +``openobjecten.object.deletes`` Reports the number of objects deleted via the API. -The objects metrics show how many entities are created, updated, or deleted via the API, +Objecttypes +----------- + +``openobjecten.objecttype.creates`` + Reports the number of objecttypes created via the API. + +``openobjecten.objecttype.updates`` + Reports the number of objecttypes updated via the API. + +``openobjecten.objecttype.deletes`` + Reports the number of objecttypes deleted via the API. + +The metrics show how many entities are created, updated, or deleted via the API, helping to monitor load and the most frequent operations, and allow for various aggregations on the data. Sample PromQL query: .. code-block:: promql - sum by (otel_scope_name) (otel_objects_object_updates_total) + sum by (otel_scope_name) (otel_openobjecten_object_updates_total) diff --git a/docs/installation/observability/otel_config.rst b/docs/installation/observability/otel_config.rst index 23878b1b..2fa04de8 100644 --- a/docs/installation/observability/otel_config.rst +++ b/docs/installation/observability/otel_config.rst @@ -18,7 +18,7 @@ Configuring the Open Telemetry sink =================================== Enabling Open Telemetry (enabled by default) requires you to have a "sink" to push the -telemetry data to. Objects API only supports the Open Telemetry Protocol (OTLP). You can +telemetry data to. Open Objecten only supports the Open Telemetry Protocol (OTLP). You can use any vendor that supports this protocol (over gRPC or HTTP/protobuf). .. tip:: We recommend the usage of the Open Telemetry diff --git a/docs/installation/oidc.rst b/docs/installation/oidc.rst index ffca1dd1..4c85c7e1 100644 --- a/docs/installation/oidc.rst +++ b/docs/installation/oidc.rst @@ -4,15 +4,15 @@ OpenID Connect configuration ============================ -Objects API supports Single Sign On (SSO) using the OpenID Connect protocol (OIDC) for the admin interface. +Open Objecten supports Single Sign On (SSO) using the OpenID Connect protocol (OIDC) for the admin interface. -Users can login to the Objects API admin interface, using their account registered by the OpenID Connect provider. In this flow: +Users can login to the admin interface, using their account registered by the OpenID Connect provider. In this flow: 1. The user clicks on *Login with organization account* in the login screen. 2. The user is redirected to the website of the OpenID Connect provider (i.e., Keycloak), where they log in with username and password (and possible Multi Factor Authentication). -3. The OIDC website sends the user back to Objects API (where the account for the user is created, if it does not yet exist). -4. An admin in Objects API assigns the account to the appropriate groups when the user logs in +3. The OIDC website sends the user back to admin interface (where the account for the user is created, if it does not yet exist). +4. An admin assigns the account to the appropriate groups when the user logs in to their account for the first time. .. note:: By default, the account is created, but it does **not** get access to the admin interface. @@ -35,8 +35,8 @@ At the end of this process, the following data must be returned (on premise): * Client ID, i.e., ``a7d14516-8b20-418f-b34e-25f53c930948`` * Client secret, i.e., ``97d663a9-3624-4930-90c7-2b90635bd990`` -Configuration of OIDC in Objects API -==================================== +Configuration of OIDC in Open Objecten +====================================== Ensure you possess the following data: diff --git a/docs/installation/prerequisites.rst b/docs/installation/prerequisites.rst index 9a0d0f20..6ce4994b 100644 --- a/docs/installation/prerequisites.rst +++ b/docs/installation/prerequisites.rst @@ -3,10 +3,9 @@ Prerequisites ============= -Objects API and Objecttypes API are most often deployed as a Docker containers. While the -`Objects API container images `_ / -`Objecttypes API container images `_ contain all the -necessary dependencies, both components require extra services to deploy the full stack. +Open Objecten is most often deployed as a Docker container. While the +`Objects API container images `_ contain all the +necessary dependencies, it requires extra services to deploy the full stack. These dependencies and their supported versions are documented here. The ``docker-compose.yml`` (not suitable for production usage!) in the root of the @@ -15,13 +14,7 @@ repository also describes these dependencies. PostgreSQL with Postgis ----------------------- -.. warning:: - - Since Objects API version 3.0.4 and Objecttypes API version 3.0.4, - PostgreSQL version 14 or higher is required. Attempting to deploy these versions - with PostgreSQL 13 or lower will result in errors! - -Objects API and Objecttypes API currently only support PostgreSQL as datastore. The Objects API is geo-capable, +Open Objecten currently only supports PostgreSQL as datastore and is is geo-capable, which requires the postgis_ extension to be enabled. The supported versions in the table below are tested in the CI pipeline. @@ -33,7 +26,7 @@ Postgis 3.2 |cross| |check| |cross| |cross| |cross| Postgis 3.5 |cross| |check| |check| |check| |check| ============ ==================== ============ ============ ============ ============ -.. warning:: Both components only support maintained versions of PostgreSQL. Once a version is +.. warning:: only maintained versions of PostgreSQL are supported. Once a version is `EOL `_, support will be dropped in the next release. diff --git a/docs/installation/quickstart.rst b/docs/installation/quickstart.rst index de37b1ea..829c2ff8 100644 --- a/docs/installation/quickstart.rst +++ b/docs/installation/quickstart.rst @@ -13,53 +13,8 @@ started quickly and these should never be used for anything besides testing: With the above remarks in mind, let's go: -Objecttypes API ---------------- - -1. Create a project folder: - - .. code:: shell - - $ mkdir objecttypes-api - $ cd objecttypes-api - -2. Download the ``docker-compose`` file: - - .. tabs:: - - .. tab:: Linux - - .. code:: shell - - $ wget https://raw.githubusercontent.com/maykinmedia/objecttypes-api/master/docker-compose.yml - - .. tab:: Windows Powershell 3 - - .. code:: shell - - PS> wget https://raw.githubusercontent.com/maykinmedia/objecttypes-api/master/docker-compose.yml - -3. Start the Docker containers: - - .. code:: shell - - $ docker compose up -d --no-build - -4. Import a demo set of objecttypes: - - .. code:: shell - - $ docker compose exec web src/manage.py loaddata demodata - -5. Create a superuser - - .. code:: shell - - $ docker compose exec web src/manage.py createsuperuser - - -Objects API ------------ +Open Objecten +------------- 1. Create a project folder: @@ -104,12 +59,12 @@ Objects API $ docker compose exec web src/manage.py createsuperuser -6. Retrieve an object via the Objects API in your webbrowser: +6. Retrieve an object via the Open Objecten API in your webbrowser: .. code:: - http://localhost:8000/api/v1/objects/ + http://localhost:8000/api/v2/objects/ -After you have the Objects API and the Objecttypes API running you can configure +After you have Open Objecten running you can configure :ref:`admin_authentication`, :ref:`admin_authorization` and use the API's. diff --git a/docs/introduction/_assets/img/multiple_objects_apis_using_national_objecttypes_api.png b/docs/introduction/_assets/img/multiple_objects_apis_using_national_objecttypes_api.png deleted file mode 100644 index ba75ce21..00000000 Binary files a/docs/introduction/_assets/img/multiple_objects_apis_using_national_objecttypes_api.png and /dev/null differ diff --git a/docs/introduction/_assets/img/objects_api_and_objecttypes_api.png b/docs/introduction/_assets/img/objects_api_and_objecttypes_api.png deleted file mode 100644 index 2128a191..00000000 Binary files a/docs/introduction/_assets/img/objects_api_and_objecttypes_api.png and /dev/null differ diff --git a/docs/introduction/_assets/img/objecttypes.png b/docs/introduction/_assets/img/objecttypes.png deleted file mode 100644 index d9bb1b56..00000000 Binary files a/docs/introduction/_assets/img/objecttypes.png and /dev/null differ diff --git a/docs/introduction/_assets/img/using_multiple_objecttypes_apis.png b/docs/introduction/_assets/img/using_multiple_objecttypes_apis.png deleted file mode 100644 index 9c4433f4..00000000 Binary files a/docs/introduction/_assets/img/using_multiple_objecttypes_apis.png and /dev/null differ diff --git a/docs/introduction/_assets/img/using_your_own_objecttypes_api.png b/docs/introduction/_assets/img/using_your_own_objecttypes_api.png deleted file mode 100644 index 4582c053..00000000 Binary files a/docs/introduction/_assets/img/using_your_own_objecttypes_api.png and /dev/null differ diff --git a/docs/introduction/background.rst b/docs/introduction/background.rst index 4005d865..3cb6ace5 100644 --- a/docs/introduction/background.rst +++ b/docs/introduction/background.rst @@ -9,13 +9,13 @@ same type of objects. Information models are often available, in various levels of completeness and each organization decides how to implement and expose these models to the outside world. -With the Objecttypes API an attempt is made to go beyond an information model +With the Objecttypes an attempt is made to go beyond an information model and create a standard on a message exchange level, in the form of JSON schema. Related initiatives ------------------- -The Objects and Objecttypes API idea is not unique but combines international +The Open Objecten API idea is not unique but combines international standards, ideas and existing applications and data models. There are several projects that are related or similar to this project. diff --git a/docs/introduction/definitions.rst b/docs/introduction/definitions.rst index 02a1706f..07958049 100644 --- a/docs/introduction/definitions.rst +++ b/docs/introduction/definitions.rst @@ -20,19 +20,7 @@ has 3 trees. That means there are 3 *objects* of *objecttype* ``tree``: #. ``height``: 5.1m, ``type``: oak #. ``height``: 5.0m, ``type``: pine tree -Objecttypes API ---------------- +Open Objecten API +----------------- -- An API to retrieve (one or more) *objecttypes*. - -Standardize various types of objects, on a national -or just as easily on a local municipality level, and make them accessible as -resources for other applications. - -Objects API ------------ - -- An API to retrieve, filter, search, write, update or delete *objects*. - -Easily store and expose various objects according to -the related *objecttype* resource in the *Objecttypes API*. +- retrieve, filter, search, write, update or delete *objects* & *objecttypes*. diff --git a/docs/introduction/features.rst b/docs/introduction/features.rst index 526ad731..91a3d72a 100644 --- a/docs/introduction/features.rst +++ b/docs/introduction/features.rst @@ -1,14 +1,11 @@ Features ======== -Below is a list of the high level features of the APIs. - -Objecttypes API ---------------- +Below is a list of the high level features of the API. * **JSON-schema validation** - When creating a new objecttype, the JSON-schema is validated. Only valid + When creating a new objecttype, the JSON-schema is validated. Only valid JSON-schemas are allowed in the objecttype. * **Versioning** @@ -18,12 +15,9 @@ Objecttypes API * **Admin interface** - You can create and inspect objecttypes via a user interface, meant for + You can create and inspect objecttypes via a user interface, meant for administrators. -Objects API ------------ - * **Objecttype validation** When creating an object, the objecttype is inspected to see if all data is @@ -31,7 +25,7 @@ Objects API * **Formal and administrative history** - The history of each object is recorded on two axes: The formal (formele) + The history of each object is recorded on two axes: The formal (formele) history and the material (materiële) history. * **Geographic search** @@ -41,8 +35,8 @@ Objects API * **Arbitrary attribute filtering** - Since the Objects API contains many different objects of different - objecttypes, the attributes are different for each objecttype. The Objects + Since the API contains many different objects of different + objecttypes, the attributes are different for each objecttype. The API supports filtering on any attribute. * **Authorizations** diff --git a/docs/introduction/index.rst b/docs/introduction/index.rst index 45d1186f..ee7a5b2c 100644 --- a/docs/introduction/index.rst +++ b/docs/introduction/index.rst @@ -24,13 +24,11 @@ configuration or development needed. :maxdepth: 1 :caption: Further reading - vision background definitions information-model uml-diagram metadata - visualization features team open-source/index diff --git a/docs/introduction/information-model.rst b/docs/introduction/information-model.rst index a4f1a350..879943bd 100644 --- a/docs/introduction/information-model.rst +++ b/docs/introduction/information-model.rst @@ -2,7 +2,7 @@ Information model ================= -The Objects and Objecttypes APIs can be represented as an information model +The Open Objecten API can be represented as an information model (IM). The IM shows the relations between classes from both APIs and makes use of the Dutch standard `Metamodel Informatiemodellering`_ (MIM). diff --git a/docs/introduction/metadata.rst b/docs/introduction/metadata.rst index 2c757e8d..dea334b4 100644 --- a/docs/introduction/metadata.rst +++ b/docs/introduction/metadata.rst @@ -1,7 +1,7 @@ Metadata ======== -The Objecttypes API includes metadata which design is based on +Objecttypes include metadata which design is based on :download:`Gezamenlijke aanpak Metadatabeheer Data in de G4 <_assets/5B.Gezamenlijke.aanpak.Metadatabeheer.Open.Data.in.de.G4.v0.2.170608.pdf>` and :download:`Datacatalogus <_assets/Verplichte.metadatavelden.-.datacatalogus.docx>`. The mapping for all Objecttypes attributes to fields from these documents is shown in the table below. diff --git a/docs/introduction/open-source/index.rst b/docs/introduction/open-source/index.rst index cbbd4d07..af44134d 100644 --- a/docs/introduction/open-source/index.rst +++ b/docs/introduction/open-source/index.rst @@ -3,10 +3,10 @@ Open-source =========== -Both the Objects API and the Objecttypes API are open-source and available +Open Objecten is open-source and available under the `EUPL license`_. -In addition, this project makes use of various open-source `Python libraries`_ +In addition, this project makes use of various open-source `Python libraries`_ and `npm packages`_ under the hood. diff --git a/docs/introduction/team.rst b/docs/introduction/team.rst index f39dec6e..e573931f 100644 --- a/docs/introduction/team.rst +++ b/docs/introduction/team.rst @@ -1,7 +1,7 @@ -Who's behind Objects and Objecttypes API? -========================================= +Who's behind the Open Objecten API? +=================================== -The Objects and Objecttypes API project was initiated by six organizations to +The Open Objecten API project was initiated by six organizations to standardize common "other" objects that are currently not exposed via an API. In alphabetical order, they are: diff --git a/docs/introduction/uml-diagram.rst b/docs/introduction/uml-diagram.rst index 83e21546..15c5f22d 100644 --- a/docs/introduction/uml-diagram.rst +++ b/docs/introduction/uml-diagram.rst @@ -10,18 +10,8 @@ This section contains UML diagrams for resources per components. These are the underlying data models and this shows the relationships between the resources, but not all attributes are the exact same as in the API. -Objects API ------------ +Open Objecten +------------- .. uml_images:: :apps: core :excluded_models: Service - - -Objecttypes API ---------------- - -Core - -.. image:: _assets/img/objecttypes.png - :width: 100% - :alt: Objecttypes UML diagram. \ No newline at end of file diff --git a/docs/introduction/versioning.rst b/docs/introduction/versioning.rst index 98864955..65f85fb0 100644 --- a/docs/introduction/versioning.rst +++ b/docs/introduction/versioning.rst @@ -3,7 +3,7 @@ Versioning policy ================= -New version releases for Objects API and Objecttypes API are done every two months, at the start of the month. +New version releases for Open Objecten are done every two months, at the start of the month. Major releases occur every two years. Each major version is supported until 24 months after the release of the next major version. @@ -18,8 +18,8 @@ is actively maintained and under active development. Older versions only receive The table below shows each major and minor version and until what date they can receive patches. -Objects API -=========== +Open Objecten +------------- +-------+---------+---------------+--------------------------+ | Major | Minor | Release date | Supported until | @@ -61,9 +61,11 @@ Objects API | | 1.0.x | 2021-01-13 | 2021-07-13 | +-------+---------+---------------+--------------------------+ - Objecttypes API -=============== +--------------- + +.. note:: Objects API was changed to Open Objecten in 4.0.0 which includes the Objecttypes API. + Active development for the standalone Objecttypes API application has stopped since version 3.4. Patches can still be applied if needed. +-------+---------+---------------+--------------------------+ | Major | Minor | Release date | Supported until | diff --git a/docs/introduction/vision.rst b/docs/introduction/vision.rst deleted file mode 100644 index e38fc39f..00000000 --- a/docs/introduction/vision.rst +++ /dev/null @@ -1,33 +0,0 @@ - -Vision -====== - -It is difficult to know and to define each object in advance and create -an appropriate API for it. This would cause significant slowdown of the -implementation of the Common Ground principles and the IT-landscape would see -a huge amount of APIs for each and every object type. - -We are therefore introducing 2 complementing APIs: - -Objecttypes API ---------------- - -At a national level, there should be a registration for all kinds of object -types. The object types hold the definition of an object and these definitions -can be obtained via an API, the Objecttypes API. - -The definition of an object can be proposed by domain experts and approved by -the VNG to become part of the national Objecttypes API. An organization can -also use its own Objecttypes API to hold definitions of locally defined objects. - -Objects API ------------ - -An organization can set up one or more Objects APIs. Each object in the Objects -API should adhere to a definition in the Objecttypes API. - -Organizations can use one Objects API to store all objects, or set up multiple -Objects API to separate between domains and/or open and internal data. - -With the above setup, applications can now easily use objects that use the same -definition in all organizations that rely on the same object type. diff --git a/docs/introduction/visualization.rst b/docs/introduction/visualization.rst deleted file mode 100644 index 807d0059..00000000 --- a/docs/introduction/visualization.rst +++ /dev/null @@ -1,49 +0,0 @@ -Visualization -============= - -The Objectypes API works together with the Objects API: Objects are of a certain -objecttype. In the examples below, there is an *objecttype tree* that is -considered the national definition. The objecttype is therefore present in the -national Objecttypes API, hosted by a public national organization, such as the -VNG. - -The municipality of Utrecht wants to store its trees according to the national -definition and indicates that the trees in its Objects API follow the -*objecttype tree* as provided in the Objecttypes API by VNG. - -As soon as the municipality of Utrecht authorizes this, trees can immediately -be stored in their Objects API. - -.. image:: _assets/img/objects_api_and_objecttypes_api.png - :width: 100% - :alt: Municipality of Utrecht using its own Objects API to store trees according to the definitions from the VNG Objecttypes API. - -Not only the municipality of Utrecht can do this. Many more -organizations can do this and store the trees that are relevant for them -according to this definition. - -.. image:: _assets/img/multiple_objects_apis_using_national_objecttypes_api.png - :width: 100% - :alt: More organizations store their trees according to the national definition. - -Every organization is free to decide which objecttypes to use but also, which -Objecttypes API to use. It's supported to run your own Objecttypes API -with your own objecttypes. This is useful if you want to deviate from national -standards or want to use other objecttypes that are not available in the -national Objecttypes API. - -In the case below, the municipality of Amsterdam decides to use their own -objecttype of a tree. They run their own Objecttypes API with that specific -objecttype in it. - -.. image:: _assets/img/using_your_own_objecttypes_api.png - :width: 100% - :alt: Municipality of Amsterdam using its own Objecttypes API. - -Eventually, the Objects API will contain objects of many different objecttypes -that can come from many different Objecttypes API. - -.. image:: _assets/img/using_multiple_objecttypes_apis.png - :width: 100% - :alt: Mixing Objecttypes API in your Objects API - diff --git a/docs/manual/migration.rst b/docs/manual/migration.rst index 074a3c05..70be1fb6 100644 --- a/docs/manual/migration.rst +++ b/docs/manual/migration.rst @@ -3,7 +3,17 @@ ObjectTypes API migration ========================= -In version 4.0.0 the ObjectTypes API will be merged into the Objects API so that only one application is needed. This means that from version 4.0.0 only objecttypes that exist in the database are supported, and no external objecttypes can be used. +In version 4.0.0 the ObjectTypes API will be merged into the Objects API so that only one application is needed (Open Objecten). +This means that from version 4.0.0 onwards only objecttypes that exist in the database are supported, and no external objecttypes can be used. + +Version flow +------------ + +Objects API versions below 3.6.0 first need be upgraded to 3.6.0 and then need to run the ``import_objecttypes`` command. After this is done, the instance can be safely upgraded to 4.0.0. +If there are remaining external objecttypes the container will fail during startup (and block any database schema changes introduced in 4.0.0) and you will need to roll back to 3.6.0. + +If it is on ``latest`` it should ideally go to 3.6.0 before upgrading to 4.0.0. If the latest tag is pulled and the container is updated, +it will not fail for remaining external objecttypes. This can be fixed by running ``import_objecttypes`` in 4.0.0 for each objecttype service. Importing objecttype data ------------------------- @@ -16,9 +26,34 @@ and update existing objecttypes or create new ones if they have not been added t The minimum version of the Objecttypes API application required for this command is 3.4.0 +.. note:: + + Objecttypen references that exist in the Objects API but have been removed from the external Objecttypes API should be removed since they cannot be imported. + .. code-block:: bash src/manage.py import_objecttypes objecttypes-api -Please note that after the update the objecttypes API is still being used in Objects API version <4.0.0, the command only fetches and imports the data. -From 4.0.0 onwards it will use the imported objecttypes. +Please note that after running this import command, the objecttypes API is still being used in Objects API version <4.0.0, the command only fetches and imports the data to prepare for the 4.0 upgrade. + +With ``check_for_external_objecttypes`` you can check if there are any remaining external objecttypes. + +.. code-block:: bash + + src/manage.py check_for_external_objecttypes + +Setup configuration +------------------- + +Because of the migration the setup configuration models have also changed. Please make sure to update the config before upgrading to 4.0.0 + +Objecttypes +^^^^^^^^^^^ + +- removed ``service_identifier`` + +TokenAuth +^^^^^^^^^ + +- removed ``use_fields`` +- removed ``fields`` diff --git a/publiccode.yaml b/publiccode.yaml index ef1c7fbd..2de8d6c9 100644 --- a/publiccode.yaml +++ b/publiccode.yaml @@ -26,7 +26,7 @@ description: nl: shortDescription: API voor het beheren van objecten documentation: 'https://objects-and-objecttypes-api.readthedocs.io/' - apiDocumentation: 'https://raw.githubusercontent.com/maykinmedia/objects-api/master/src/objects/api/v1/openapi.yaml' + apiDocumentation: 'https://raw.githubusercontent.com/maykinmedia/objects-api/master/src/objects/api/v2/openapi.yaml' features: - Objecten API - Minimalistische objecten beheerinterface @@ -45,7 +45,7 @@ description: en: shortDescription: API to manage objects documentation: 'https://objects-and-objecttypes-api.readthedocs.io/' - apiDocumentation: 'https://raw.githubusercontent.com/maykinmedia/objects-api/master/src/objects/api/v1/openapi.yaml' + apiDocumentation: 'https://raw.githubusercontent.com/maykinmedia/objects-api/master/src/objects/api/v2/openapi.yaml' features: - Objects API - Minimalistic object management interface diff --git a/src/objects/accounts/metrics.py b/src/objects/accounts/metrics.py index d42a8c46..6dccb628 100644 --- a/src/objects/accounts/metrics.py +++ b/src/objects/accounts/metrics.py @@ -6,7 +6,7 @@ from .models import User -meter = metrics.get_meter("objects.accounts") +meter = metrics.get_meter("openobjecten.accounts") def count_users(options: metrics.CallbackOptions) -> Collection[metrics.Observation]: @@ -32,32 +32,32 @@ def count_users(options: metrics.CallbackOptions) -> Collection[metrics.Observat meter.create_observable_gauge( - name="objects.auth.user_count", + name="openobjecten.auth.user_count", description="The number of application users in the database.", unit=r"{user}", # no unit so that the _ratio suffix is not added callbacks=[count_users], ) logins = meter.create_counter( - "objects.auth.logins", + "openobjecten.auth.logins", unit="1", # unitless count description="The number of successful user logins.", ) logouts = meter.create_counter( - "objects.auth.logouts", + "openobjecten.auth.logouts", unit="1", # unitless count description="The number of user logouts.", ) login_failures = meter.create_counter( - "objects.auth.login_failures", + "openobjecten.auth.login_failures", unit="1", # unitless count description="The number of failed logins by users, including the admin.", ) user_lockouts = meter.create_counter( - "objects.auth.user_lockouts", + "openobjecten.auth.user_lockouts", unit="1", # unitless count description="The number of user lockouts because of failed logins.", ) diff --git a/src/objects/api/metrics.py b/src/objects/api/metrics.py index 06a23d72..b385781f 100644 --- a/src/objects/api/metrics.py +++ b/src/objects/api/metrics.py @@ -1,37 +1,35 @@ from opentelemetry import metrics -object_meter = metrics.get_meter("objects.api") +openobjecten_meter = metrics.get_meter("openobjecten.api") -objects_create_counter = object_meter.create_counter( - "objects.object.creates", +objects_create_counter = openobjecten_meter.create_counter( + "openobjecten.object.creates", description="Amount of objects created (via the API).", unit="1", ) -objects_update_counter = object_meter.create_counter( - "objects.object.updates", +objects_update_counter = openobjecten_meter.create_counter( + "openobjecten.object.updates", description="Amount of objects updated (via the API).", unit="1", ) -objects_delete_counter = object_meter.create_counter( - "objects.object.deletes", +objects_delete_counter = openobjecten_meter.create_counter( + "openobjecten.object.deletes", description="Amount of objects deleted (via the API).", unit="1", ) -objecttype_meter = metrics.get_meter("objecttypes.api.v2") - -objecttype_create_counter = objecttype_meter.create_counter( - "objecttypes.objecttype.creates", +objecttype_create_counter = openobjecten_meter.create_counter( + "openobjecten.objecttype.creates", description="Amount of objecttypes created (via the API).", unit="1", ) -objecttype_update_counter = objecttype_meter.create_counter( - "objecttypes.objecttype.updates", +objecttype_update_counter = openobjecten_meter.create_counter( + "openobjecten.objecttype.updates", description="Amount of objecttypes updated (via the API).", unit="1", ) -objecttype_delete_counter = objecttype_meter.create_counter( - "objecttypes.objecttype.deletes", +objecttype_delete_counter = openobjecten_meter.create_counter( + "openobjecten.objecttype.deletes", description="Amount of objecttypes deleted (via the API).", unit="1", ) diff --git a/src/objects/core/management/commands/check_for_external_objecttypes.py b/src/objects/core/management/commands/check_for_external_objecttypes.py index cedc8967..88f8a571 100644 --- a/src/objects/core/management/commands/check_for_external_objecttypes.py +++ b/src/objects/core/management/commands/check_for_external_objecttypes.py @@ -20,11 +20,11 @@ def handle(self, *args, **options): for objecttype in ObjectType.objects.iterator(): if not objecttype.is_imported: external_object_count += 1 - external_uuids.add(objecttype.uuid) - - msg = f"{external_object_count} objectype(s) have not been imported: {external_uuids}" - - self.stdout.write(self.style.ERROR(msg)) + external_uuids.add(str(objecttype.uuid)) if external_object_count > 0: - raise CommandError(msg) + raise CommandError( + f"{external_object_count} objectype(s) have not been imported: {', '.join(external_uuids)}" + ) + else: + self.stdout.write(self.style.SUCCESS("OK")) diff --git a/src/objects/core/management/commands/import_objecttypes.py b/src/objects/core/management/commands/import_objecttypes.py index 7531935f..a0223689 100644 --- a/src/objects/core/management/commands/import_objecttypes.py +++ b/src/objects/core/management/commands/import_objecttypes.py @@ -83,6 +83,7 @@ def _bulk_create_or_update_objecttypes(self, data): "uuid", ], update_fields=[ + "is_imported", "name", "name_plural", "description", @@ -128,6 +129,7 @@ def _parse_objecttype_data( objecttype.pop("linkableToZaken", None) objecttype.pop("versions") objecttype.pop("url") + objecttype["is_imported"] = True data.append(ObjectType(**underscoreize(objecttype))) return data diff --git a/src/objects/setup_configuration/steps/objecttypes.py b/src/objects/setup_configuration/steps/objecttypes.py index d2bc2b6b..1a1c8e33 100644 --- a/src/objects/setup_configuration/steps/objecttypes.py +++ b/src/objects/setup_configuration/steps/objecttypes.py @@ -10,11 +10,10 @@ class ObjectTypesConfigurationStep(BaseConfigurationStep): """ - Configure references to objecttypes in the Objecttypes API. + Configure references to objecttypes in Open Objecten. - .. note:: Note that these objecttypes references should match instances in the Objecttypes API. Currently - there is no configuration step to do this automatically, so these have to be configured - manually or by loading fixtures. + .. note:: This step was previously used to preconfigure objecttypes from a separate Objecttypes API, + since 4.0.0 Objecttypes and Objects have been merged into one, and this step is only for preloading of objecttype names & uuids. """ config_model = ObjectTypesConfigurationModel diff --git a/src/objects/setup_configuration/steps/token_auth.py b/src/objects/setup_configuration/steps/token_auth.py index 592563c7..c77ad962 100644 --- a/src/objects/setup_configuration/steps/token_auth.py +++ b/src/objects/setup_configuration/steps/token_auth.py @@ -18,17 +18,13 @@ class TokenAuthConfigurationStep( BaseConfigurationStep[TokenAuthGroupConfigurationModel] ): """ - Configure tokens with permissions for other applications to access Objects API - - .. note:: To ensure the proper functioning of the tokens, it is essential to first - configure the ``objecttypes``. Then, the token configuration must be completed - to guarantee the correct configuration of the ``Permissions``. + Configure tokens with permissions for other applications to access Open Objecten """ namespace = "tokenauth" enable_setting = "tokenauth_config_enable" - verbose_name = "Configuration to set up authentication tokens for objects" + verbose_name = "Configuration to set up authentication tokens" config_model = TokenAuthGroupConfigurationModel def _full_clean(self, instance: object) -> None: diff --git a/src/objects/templates/index.html b/src/objects/templates/index.html index 519c2613..476c5858 100644 --- a/src/objects/templates/index.html +++ b/src/objects/templates/index.html @@ -15,11 +15,6 @@ voor Open Data, waarbij de geregistreerde objecten publiekelijk toegankelijk zijn.

-

- Om het formaat van objecten, de zogenoemde objecttypen, vast te leggen wordt - gebruik gemaakt van de landelijke en/of een lokale - Objecttypen API. -

{% endblock content_nl %} {% block content_en %} @@ -29,11 +24,6 @@ relevant objects. An organization can also choose to use the Objects API to expose objects to the public, as Open Data.

-

- To define the format of objects, so called object types, organizations can use - a national and/or local - Objecttypes API. -

{% endblock content_en %} diff --git a/src/objects/templates/open_api_framework/env_config.rst b/src/objects/templates/open_api_framework/env_config.rst index 6544c7db..a5d53f11 100644 --- a/src/objects/templates/open_api_framework/env_config.rst +++ b/src/objects/templates/open_api_framework/env_config.rst @@ -1,7 +1,7 @@ {% extends "open_api_framework/env_config.rst" %} {% block intro %} -The Objects and Objecttypes APIs can be run both as a Docker container or a VPS / dedicated server. +Open Objecten can be run as a Docker container or a VPS / dedicated server. It relies on other services, such as database and cache backends, which can be configured through environment variables. {% endblock %} @@ -10,10 +10,10 @@ It relies on other services, such as database and cache backends, which can be c Initial superuser creation (Docker only) ---------------------------------------- -A clean installation of Objects API comes without pre-installed or pre-configured admin +A clean installation of Open Objecten comes without pre-installed or pre-configured admin user by default. -Users of Objects API can opt-in to provision an initial superuser via environment +Users can opt-in to provision an initial superuser via environment variables. The user will only be created if it doesn't exist yet. * ``OBJECTS_SUPERUSER_USERNAME``: specify the username of the superuser to create. Setting @@ -27,8 +27,8 @@ variables. The user will only be created if it doesn't exist yet. Initial configuration --------------------- -Both Objects API and Objecttypes API support `setup_configuration` management command, +Open Objecten supports the `setup_configuration` management command, which allows configuration via environment variables. All these environment variables are described at :ref:`command line `. -{% endblock %} \ No newline at end of file +{% endblock %}