update dependency and core api docs (#1922)

docs_manual/source/admin_install.rst

@@ -17,26 +17,22 @@ environment. All these components are required for running the complete feature
 set of SODAR. However, it is also possible to run some of these outside of the
 Docker Compose network if e.g. you already have a separate iRODS server running.
 
-- Essential SODAR Components
+Essential SODAR Components
     - ``sodar-web``: The SODAR web server for main program logic and UIs.
     - ``sodar-celeryd-default``: Celery daemon for background jobs.
     - ``sodar-celerybeat``: Celery service for periodic tasks.
-- Database Servers
-    - ``postgres``: PostgreSQL server for SODAR and iRODS databases.
+Database Servers
+    - ``postgres``: PostgreSQL server for SODAR and iRODS databases. Minimum
+      supported version is v12, recommended version is v16.
     - ``redis``: In-memory database for Celery jobs and caching.
-- iRODS Servers
-    - ``irods``: An iRODS iCAT server for file storage.
+iRODS Servers
+    - ``irods``: An iRODS iCAT server for file storage. The minimum supported
+      version is v4.3.
     - ``davrods``: iRODS WebDAV server for web access and IGV/UCSC integration.
-- Networking
+Networking
     - ``traefik``: Reverse proxy for TLS/SSL routing.
     - ``sssd``: System Security Service Daemon for LDAP/AD authentication.
 
-.. note::
-
-    Currently the sodar-docker-compose environment only supports iRODS v4.2.
-    Support for v4.3 is being worked on. iRODS v4.3 will be the default
-    supported version from SODAR v1.0 onwards.
-
 
 Quickstart Guide
 ================
@@ -60,15 +56,15 @@ Prerequisites
 Ensure your system matches the following operating system and software
 requirements.
 
-- Hardware
+Hardware
     - ~10 GB of disk space for the Docker images
-- Operating System
+Operating System
     - A modern Linux distribution that is
       `supported by Docker <https://docs.docker.com/engine/install/#server>`_.
     - Outgoing HTTPS connections to the internet are allowed to download data
       and Docker images.
     - Server ports 80 and 443 are open and free on the host.
-- Software
+Software
     - `Docker <https://docs.docker.com/get-docker/>`_
     - `Docker Compose <https://docs.docker.com/compose/install/>`_
     - `OpenSSL <https://www.openssl.org/>`_
@@ -279,7 +275,7 @@ production is generally recommended only for experienced SODAR admins.
 
 .. note::
 
-    SODAR v1.0 will be upgraded to use iRODS 4.3 and Postgres v16. This version
+    SODAR v1.0 has been upgraded to use iRODS 4.3 and Postgres v16. This version
     may require special steps for upgrading an existing environment. Make sure
     to refer to the sodar-docker-compose README for instructions.
 
@@ -348,7 +344,7 @@ Production Prerequisites
 In addition to the :ref:`general prerequisites <admin_install_prerequisites>`,
 we recommend the following for a production deployment of SODAR:
 
-- Recommended Hardware
+Recommended Hardware
     - Memory: 64 GB of RAM
     - CPU: 16 cores
     - Disk: 600+ GB of free and **fast** disk space

docs_manual/source/api_documentation.rst

@@ -20,7 +20,7 @@ The API supports authentication through Knox authentication tokens as well as
 logging in using your SODAR username and password. Tokens are the recommended
 method for security purposes.
 
-For token access, first retrieve your token using the **API Tokens** site app
+For token access, first retrieve your token using the :ref:`ui_api_tokens` app
 on the SODAR web UI. Note that you can you only see the token once when creating
 it.
 
@@ -34,22 +34,32 @@ follows:
 Versioning
 ----------
 
+.. note::
+
+    API versioning has had a major overhaul in SODAR v1.0. Some changes are
+    breaking with no backwards compatibility. Please review this part of the
+    document carefully and adjust your clients accordingly.
+
 The SODAR REST API uses accept header versioning. While specifying the desired
 API version in your HTTP requests is optional, it is **strongly recommended**.
 This ensures you will get the appropriate return data and avoid running into
 unexpected incompatibility issues.
 
 To enable versioning, add the ``Accept`` header to your request with the
-following media type and version syntax. Replace the version number with your
-expected version.
+appropriate media type of your API and the expected version. From SODAR v1.0
+onwards, both the media type and the version are specific for a SODAR Server or
+SODAR Core application, as each provides their independent API which may
+introduce new versions independent of other APIs.
+
+Example for the SODAR Server samplesheets API:
 
 .. code-block:: console
 
-    Accept: application/vnd.bihealth.sodar+json; version=0.15.0
+    Accept: application/vnd.bihealth.sodar.samplesheets+json; version=1.0
+
+For detailed media types and versioning information of each API, see the
+respective application API documentation.
 
-Specific sections of the SODAR API may require their own accept header. See the
-exact header requirement in the respective documentation on each section of the
-API.
 
 Model Access and Permissions
 ----------------------------
@@ -71,3 +81,22 @@ specified.
 If return data is not specified in the documentation of an API view, it will
 return the appropriate HTTP status code along with an optional ``detail`` JSON
 field upon a successfully processed request.
+
+Pagination
+----------
+
+From SODAR V1.0 onwards, list views support pagination unless otherwise
+specified. Pagination can be enabled by providing the ``?page=x`` query string
+in the API request. This will change the return data into a paginated format.
+Example:
+
+.. code-block:: python
+
+    {
+        'count' 170,
+        'next': 'api/url?page=3',
+        'previous': 'api/url?page=1',
+        'results': [
+            # ...
+        ]
+    }

docs_manual/source/api_examples.rst

@@ -40,10 +40,12 @@ the SODAR API:
     # Headers for requests:
     # Token authorization header (required)
     auth_header = {'Authorization': 'token {}'.format(api_token)}
-    # Use core_headers for project management API endpoints
-    core_headers = {**auth_header, 'Accept': 'application/vnd.bihealth.sodar-core+json; version=0.13.4'}
-    # Use sodar_headers for sample sheet and landing zone API endpoints
-    sodar_headers = {**auth_header, 'Accept': 'application/vnd.bihealth.sodar+json; version=0.15.0'}
+    # Use project_headers for project management API endpoints
+    project_headers = {**auth_header, 'Accept': 'application/vnd.bihealth.sodar-core.projectroles+json; version=1.0'}
+    # Use the following headers for sample sheet and landing zone API endpoints
+    sheet_headers = {**auth_header, 'Accept': 'application/vnd.bihealth.sodar.samplesheets+json; version=1.0'}
+    zone_headers = {**auth_header, 'Accept': 'application/vnd.bihealth.sodar.landingzones+json; version=1.0'}
+
 
 .. note::
 
@@ -58,7 +60,7 @@ categories and projects available to you with the following request:
 .. code-block:: python
 
     url = sodar_url + '/project/api/list'
-    projects = requests.get(url, headers=core_headers).json()
+    projects = requests.get(url, headers=project_headers).json()
 
 
 Create Project
@@ -72,14 +74,15 @@ required for most subsequent operations you wish to perform on that project.
 
     url = sodar_url + '/project/api/create'
     data = {'title': 'New Project via API', 'type': 'PROJECT', 'parent': category_uuid, 'owner': user_uuid}
-    project = requests.post(url, data=data, headers=core_headers).json()
+    project = requests.post(url, data=data, headers=project_headers).json()
     project_uuid = project['sodar_uuid']
 
 .. note::
 
-    Note the use of ``core_headers`` here, as the project management API comes
+    Note the use of ``project_headers`` here, as the project management API comes
     from the `SODAR Core <https://sodar-core.readthedocs.io>`_ package, which
-    has its own API and versioning.
+    has its own API and versioning. See the related
+    `SODAR Core API documentation <https://sodar-core.readthedocs.io/en/latest/app_projectroles_api_rest.html#api-views>`_.
 
 
 Assign a Member Role
@@ -94,7 +97,7 @@ including its UUID for future updates.
     other_user_uuid = '33333333-3333-3333-3333-333333333333'
     url = sodar_url + '/project/api/roles/create/' + project_uuid
     data = {'role': 'project contributor', 'user': other_user_uuid}
-    response_data = requests.post(url, data=data, headers=core_headers).json()
+    response_data = requests.post(url, data=data, headers=project_headers).json()
     role_uuid = response_data.get('role_uuid')
 
 
@@ -111,15 +114,15 @@ archived ISA-Tab.
     url = sodar_url + '/samplesheets/api/import/' + project_uuid
     sheet_path = '/tmp/your_isa_tab.zip'
     files = {'file': ('your_isa_tab.zip', open(sheet_path, 'rb'), 'application/zip')}
-    response = requests.post(url, files=files, headers=sodar_headers)
+    response = requests.post(url, files=files, headers=sheet_headers)
 
 To ensure your import was successful, you can retrieve investigation information
 via the API. This also returns e.g. the UUIDs for studies and assays:
 
 .. code-block:: python
 
     url = sodar_url + '/samplesheets/api/investigation/retrieve/' + project_uuid
-    inv_info = requests.get(url, headers=sodar_headers).json()
+    inv_info = requests.get(url, headers=sheet_headers).json()
 
 
 Export Sample Sheets
@@ -132,7 +135,7 @@ providing the TSV data to e.g. parsers for further editing.
 .. code-block:: python
 
     url = sodar_url + '/samplesheets/api/export/json/' + project_uuid
-    response_data = requests.get(url, headers=sodar_headers).json()
+    response_data = requests.get(url, headers=sheet_headers).json()
     print(response_data.keys())
     # dict_keys(['investigation', 'studies', 'assays', 'date_modified'])
 
@@ -167,7 +170,7 @@ the path to the sample repository collection in your project.
 .. code-block:: python
 
     url = sodar_url + '/samplesheets/api/irods/collections/create/' + project_uuid
-    response = requests.post(url, headers=sodar_headers)
+    response = requests.post(url, headers=sheet_headers)
     irods_path = response.json().get('path')
 
 The API request below initiates the process for creating a landing zone. You
@@ -178,7 +181,7 @@ investigation information API endpoint as detailed above.
 
     url = sodar_url + '/landingzones/api/create/' + project_uuid
     data = {'assay': assay_uuid}
-    response = requests.post(url, data=data, headers=sodar_headers)
+    response = requests.post(url, data=data, headers=zone_headers)
     zone_uuid = response.json().get('sodar_uuid')
 
 As with most landing zone operations, the landing zone creation process is
@@ -188,7 +191,7 @@ before proceeding with file uploads:
 .. code-block:: python
 
     url = sodar_url + '/landingzones/api/retrieve/' + zone_uuid
-    response_data = requests.get(url, headers=sodar_headers).json()
+    response_data = requests.get(url, headers=zone_headers).json()
     if response_data.get('status') == 'ACTIVE':
         pass  # OK to proceed
 
@@ -199,7 +202,7 @@ moving process as follows:
 .. code-block:: python
 
     url = sodar_url + '/landingzones/api/submit/move/' + zone_uuid
-    response = requests.post(url, headers=sodar_headers)
+    response = requests.post(url, headers=zone_headers)
 
 Once the landing zone status is returned as ``MOVED``, the landing zone files
 have been moved into the project sample data repository and the zone has been
@@ -208,6 +211,6 @@ deleted.
 .. code-block:: python
 
     url = sodar_url + '/landingzones/api/retrieve/' + zone_uuid
-    response_data = requests.get(url, headers=sodar_headers).json()
+    response_data = requests.get(url, headers=zone_headers).json()
     if response_data.get('status') == 'MOVED':
         pass  # Moving was successful

docs_manual/source/api_projectroles.rst

@@ -7,20 +7,22 @@ The REST API for project access and management operations is described in this
 document.
 
 
-API Views
-=========
-
-The project management API is provided by the SODAR Core package. The
-documentation for the REST API views can be found in the
-`SODAR Core Documentation <https://sodar-core.readthedocs.io/en/latest/app_projectroles_api_rest.html#api-views>`_.
-
-
 Versioning
 ==========
 
-For accept header versioning, the following media type and version are expected
-in the current SODAR version:
+Media Type
+    ``application/vnd.bihealth.sodar-core.projectroles+json``
+Current Version
+    ``1.0``
+Accepted Versions
+    ``1.0``
+Header Example
+    ``Accept: application/vnd.bihealth.sodar-core.projectroles+json; version=x.y``
+
 
-.. code-block:: console
+API Views
+=========
 
-    Accept: application/vnd.bihealth.sodar-core+json; version=0.13.3
+The project management API is provided by the SODAR Core package. The
+documentation for the REST API views can be found in the
+`SODAR Core documentation <https://sodar-core.readthedocs.io/en/latest/app_projectroles_api_rest.html#api-views>`_.

docs_manual/source/dev_install.rst

@@ -21,8 +21,8 @@ System requirements for SODAR development are as follows:
     - Other Ubuntu versions and Linux distributions may work but are not
       supported. The instructions in this section assume the use of Ubuntu
       20.04.
-- Python 3.8, 3.9 or 3.10
-    - 3.8 recommended.
+- Python 3.9, 3.10 or 3.11
+    - 3.11 is recommended.
 - `Docker <https://docs.docker.com/get-docker/>`_
 - `Docker Compose <https://docs.docker.com/compose/install/>`_
 - `OpenSSL <https://www.openssl.org/>`_
@@ -34,7 +34,7 @@ SODAR Docker Compose Setup
 In addition to the ``sodar-server`` repository, the following components are
 required for SODAR development:
 
-- PostgreSQL
+- PostgreSQL v12+ (v16 recommended)
 - Redis
 - Main iRODS server
 - Test iRODS server