Merge pull request #89 from maykinmedia/feature/more-docs

Added more documentation

docs/api/index.rst

@@ -0,0 +1,25 @@
+.. _api_index:
+
+==================
+API-specifications
+==================
+
+The Objects API and Objecttypes API are proposed as VNG API standards and are
+currently in review. Their specifications can be found below.
+
+======================  ==========================================
+API                     Specification version(s)
+======================  ==========================================
+`Objecttypes API`_      1.0.0-alpha (
+                        `Redoc <https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/maykinmedia/objecttypes-api/master/src/openapi.yaml>`__,
+                        `Swagger <https://petstore.swagger.io/?url=https://raw.githubusercontent.com/maykinmedia/objecttypes-api/master/src/openapi.yaml>`__
+                        )
+`Objects API`_          1.0.0-alpha (
+                        `Redoc <https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/maykinmedia/objects-api/master/src/openapi.yaml>`__,
+                        `Swagger <https://petstore.swagger.io/?url=https://raw.githubusercontent.com/maykinmedia/objects-api/master/src/openapi.yaml>`__
+                        )
+======================  ==========================================
+
+.. _`Objecttypes API`: https://github.com/maykinmedia/objecttypes-api
+
+.. _`Objects API`: https://github.com/maykinmedia/objects-api

docs/conf.py

@@ -41,7 +41,8 @@
 # ones.
 extensions = [
     "sphinx.ext.todo",
-#    "recommonmark",
+    "sphinx_tabs.tabs",
+    "recommonmark",
 #    "sphinx_markdown_tables",
 ]
 

docs/index.rst

@@ -1,8 +1,8 @@
 Documentation
 =============
 
-The Objects API and the Objecttypes API are two components that complement 
-eachother. The Objecttypes API holds the object definitions for objects that 
+The :ref:`Objects API` and the Objecttypes API are two components that complement 
+eachother. The :ref:`Objecttypes API` holds the object definitions for objects that 
 can be stored in the Objects API. Together they provide a powerfull way to 
 create and store any kind of object. They are designed line with the 
 `Common Ground`_ model and they can be used by other API's that need to store
@@ -19,22 +19,43 @@ Getting started
 To get you started, you might find some of these links relevant:
 
 * New to this project? Have a look at the :ref:`introduction_index`
+* New to the API? Read up on the :ref:`api_index`.
+* Want to get started now? Follow the :ref:`installation_quickstart`
 
 
-Objects API
------------
-
-TODO
-
+.. _Objecttypes API:
 
 Objecttypes API
 ---------------
 
-TODO
+The Objecttypes API aims to standardize various types of objects, on a national
+level, in an accessible way and without the need to create a whole new API for
+each (simple) object.
+
+This national Objecttypes API is required for registering objects in local
+:ref:`Objects APIs`. Organisations can also run an Objecttypes API locally, to use
+both national and local definitions of objects.
+
+
+.. _Objects API:
+.. _Objects APIs:
+
+Objects API
+-----------
+
+The Objects API aims to easily store and expose various objects and make them 
+available in standardized format. The Objects API can be used by any 
+organization to manage 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 :ref:`Objecttypes API`.
 
 
 .. toctree::
    :maxdepth: 2
    :hidden:
 
    introduction/index
+   api/index
+   installation/index

docs/installation/config.md

@@ -0,0 +1,76 @@
+# Environment configuration reference
+
+The Objects and Objecttypes API can be ran both as a Docker container or directly on a VPS or
+dedicated server. It relies on other services, such as database and cache
+backends, which can be configured through environment variables.
+
+## Available environment variables
+
+### Required
+
+* `DJANGO_SETTINGS_MODULE`: which environment settings to use. Available options:
+  - `openpersonen.conf.docker`
+  - `openpersonen.conf.dev`
+  - `openpersonen.conf.ci`
+
+* `SECRET_KEY`: secret key that's used for certain cryptographic utilities. You
+  should generate one via
+  [miniwebtool](https://www.miniwebtool.com/django-secret-key-generator/)
+
+* `ALLOWED_HOSTS`: a comma separated (without spaces!) list of domains that
+  serve the installation. Used to protect against `Host` header attacks.
+
+### Optional
+
+* `SITE_ID`: defaults to `1`. The database ID of the site object. You usually
+  won't have to touch this.
+
+* `DEBUG`: defaults to `False`. Only set this to `True` on a local development
+  environment. Various other security settings are derived from this setting!
+
+* `IS_HTTPS`: defaults to the inverse of `DEBUG`. Used to construct absolute
+  URLs and controls a variety of security settings.
+
+* `DB_HOST`: hostname of the PostgreSQL database. Defaults to `localhost`,
+  unless you're using the `docker` environment, then it defaults to `db`.
+
+* `DB_USER`: username of the database user. Defaults to `openzaak`,
+  unless you're using the `docker` environment, then it defaults to `postgres`.
+
+* `DB_PASSWORD`: password of the database user. Defaults to `openzaak`,
+  unless you're using the `docker` environment, then it defaults to no password.
+
+* `DB_NAME`: name of the PostgreSQL database. Defaults to `openzaak`,
+  unless you're using the `docker` environment, then it defaults to `postgres`.
+
+* `DB_PORT`: port number of the database, defaults to `5432`.
+
+* `SENTRY_DSN`: URL of the sentry project to send error reports to. Default
+  empty, i.e. -> no monitoring set up. Highly recommended to configure this.
+
+## Specifying the environment variables
+
+There are two strategies to specify the environment variables:
+
+* provide them in a `.env` file
+* start the Open Zaak processes (with uwsgi/gunicorn/celery) in a process
+  manager that defines the environment variables
+
+### Providing a .env file
+
+This is the most simple setup and easiest to debug. The `.env` file must be
+at the root of the project - i.e. on the same level as the `src` directory (
+NOT _in_ the `src` directory).
+
+The syntax is key-value:
+
+```
+SOME_VAR=some_value
+OTHER_VAR="quoted_value"
+```
+
+### Provide the envvars via the process manager
+
+If you use a process manager (such as supervisor/systemd), use their techniques
+to define the envvars. The Open Zaak implementation will pick them up out of
+the box.

docs/installation/index.rst

@@ -0,0 +1,18 @@
+.. _installation_index:
+
+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. 
+
+For the sake of simplicity, we have chosen to use Docker and Docker Compose for 
+this.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Further reading
+
+   quickstart
+   config

docs/installation/quickstart.rst

@@ -0,0 +1,99 @@
+.. _installation_quickstart:
+
+Quickstart
+==========
+
+A simple ``docker-compose-quickstart.yml`` file is available to get the API's
+up and running in minutes. This file has some convenience settings to get 
+started quickly and these should never be used for anything besides testing:
+
+* A default secret is set in the ``SECRET_KEY`` environment variable
+* A predefined database and database account is used.
+* API authorizations are disabled.
+
+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-quickstart.yml -O docker-compose.yml
+
+      .. tab:: Windows Powershell 3
+
+         .. code:: shell
+
+            PS> wget https://raw.githubusercontent.com/maykinmedia/objecttypes-api/master/docker-compose-quickstart.yml -Odocker-compose.yml
+
+3. Start the Docker containers:
+
+   .. code:: shell
+
+      $ docker-compose up -d
+
+4. Import a demo set of objecttypes:
+
+   .. code:: shell
+
+      $ docker-compose -f docker-compose-quickstart.yml exec web src/manage.py loaddata demodata
+
+Objects API
+-----------
+
+1. Create a project folder:
+
+   .. code:: shell
+
+      $ mkdir objects-api
+      $ cd objects-api
+
+2. Download the ``docker-compose`` file:
+
+   .. tabs::
+
+      .. tab:: Linux
+
+         .. code:: shell
+
+            $ wget https://raw.githubusercontent.com/maykinmedia/objects-api/master/docker-compose-quickstart.yml -O docker-compose.yml
+
+      .. tab:: Windows Powershell 3
+
+         .. code:: shell
+
+            PS> wget https://raw.githubusercontent.com/maykinmedia/objects-api/master/docker-compose-quickstart.yml -Odocker-compose-quickstart.yml
+
+3. Start the Docker containers:
+
+   .. code:: shell
+
+      $ docker-compose up -d
+
+4. Import a demo set of objects (linking to the demo objecttypes):
+
+   .. code:: shell
+
+      $ docker-compose exec web src/manage.py loaddata demodata
+
+5. Retrieve an object via the Objects API in your webbrowser:
+
+   .. code:: 
+
+      http://localhost:8000/api/v1/objects/
+
+
+TODO: Auth, fixtures, objects...

docs/introduction/definitions.rst

@@ -0,0 +1,39 @@
+Definitions
+===========
+
+Objecttype
+----------
+
+A definition, represented as a JSON-schema, together with metadata about the 
+objecttype. Each *objecttype* represents a collection of *objects* of similar form 
+and/or function.
+
+Object
+------
+
+A self-contained entity of data with its own identity, structured according to
+the JSON-schema of the *objecttype*.
+
+*Example*
+
+The *objecttype tree* has 2 attributes: `height` and `type`. A particular street 
+has 3 trees, or rather, *3 objects of objecttype tree*, and they are: 1) 
+`height`: 4.9m, `type`: oak, 2) `height`: 5.1m, `type`: oak, 3) `height`: 5.0m, 
+`type`: pine tree.
+
+Objecttypes API
+---------------
+
+An API to retrieve one or more *objecttypes*.
+
+The Objecttypes API aims to 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*.
+
+The Objects API aims to easily store and expose various objects according to 
+the related **objecttype resource** in the *Objecttypes API*.

docs/introduction/features.rst

@@ -0,0 +1,51 @@
+Features
+========
+
+Below is a list of the high level features of the APIs.
+
+Objecttypes API
+---------------
+
+* **JSON-schema validation**
+
+  When creating a new objecttype, the JSON-schema is validated. Only valid 
+  JSON-schemas are allowed in the objecttype.
+
+* **Versioning**
+
+  Objecttypes are versioned. This means you can create an objecttype but if the
+  objecttype evolves, you can create a new version.
+
+* **Admin interface**
+
+  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
+  formatted according to the JSON-schema in the objecttype.
+
+* **Formal and administrative history**
+
+  The history of each object is recorded on two axes: The formal (formele) 
+  history and the material (materiële) history.
+
+* **Geographic search**
+
+  Objects can be searched with GeoJSON using an arbitrary geographical point or
+  polygon.
+
+* **Arbitrary attribute filtering**
+
+  Since the Objects API contains many different objects of different 
+  objecttypes, the attributes are different for each objecttype. The Objects
+  API supports filtering on any attribute.
+
+* **Authorizations**
+
+  With an API-token applications can get read or write access, per objecttype.
+  These API-tokens can be configured in the admin interface.