📝 [#564] refactor docs for objecttype migrations

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

README.rst

@@ -1,14 +1,14 @@
-===========
-Objects API
-===========
+=============
+Open Objecten
+=============
 
 :Version: 3.6.0
 :Source: https://github.com/maykinmedia/objects-api
 :Keywords: objects, assets, zaakobjecten
 
 |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

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
+.. _`Maykin`: https://www.maykinmedia.nl

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.

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.
 

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