Merge pull request #863 from bareos/dev/maik/master/rest_api_pypi

rest-api: add pypi packaging files

.github/workflows/publish-release-to-pypi.yml → .github/workflows/publish_python-bareos_to_pypi.yml

@@ -8,7 +8,7 @@ on:
 jobs:
   build-and-publish:
     name: "Build python-bareos and publish it to https://pypi.org/"
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-20.04
 
     steps:
     - name: "Checkout source"
@@ -21,7 +21,7 @@ jobs:
       run:  git fetch --tag
 
     - name: "Set up Python"
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v2
       with:
         python-version: 3.7
 
@@ -43,7 +43,7 @@ jobs:
         path: python-bareos/dist/
 
     - name: "Publish to pypi.org"
-      uses: pypa/gh-action-pypi-publish@v1.1.0
+      uses: pypa/gh-action-pypi-publish@v1.4.2
       with:
         password: ${{ secrets.pypi_password }}
         packages_dir: python-bareos/dist/

.github/workflows/publish-to-test-pypi.yml → .github/workflows/publish_python-bareos_to_test-pypi.yml

@@ -3,7 +3,7 @@ name: "python-bareos -> https://test.pypi.org/"
 #
 # build a python-bareos dev package
 # for every change in master,
-# affecting python-bareos.
+# affecting the relevant files.
 #
 
 on:
@@ -12,12 +12,12 @@ on:
       - master
     paths:
       - python-bareos/**
-      - .github/workflows/publish-to-test-pypi.yml
+      - .github/workflows/publish_python-bareos_to_test-pypi.yml
 
 jobs:
   build-and-publish:
     name: "Build python-bareos and publish it to https://test.pypi.org/"
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-20.04
 
     steps:
     - name: "Checkout source"
@@ -30,7 +30,7 @@ jobs:
       run:  git fetch --tag
 
     - name: "Set up Python"
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v2
       with:
         python-version: 3.7
 
@@ -52,7 +52,7 @@ jobs:
         path: python-bareos/dist/
 
     - name: "Publish to test.pypi.org"
-      uses: pypa/gh-action-pypi-publish@v1.1.0
+      uses: pypa/gh-action-pypi-publish@v1.4.2
       with:
         repository_url: https://test.pypi.org/legacy/
         password: ${{ secrets.test_pypi_password }}

.github/workflows/publish_restapi_to_pypi.yml

@@ -0,0 +1,49 @@
+name: "[Release] bareos-restapi -> https://pypi.org/"
+
+on:
+  push:
+    tags:
+      - Release/*
+
+jobs:
+  build-and-publish:
+    name: "Build bareos-restapi and publish it to https://pypi.org/"
+    runs-on: ubuntu-20.04
+
+    steps:
+    - name: "Checkout source"
+      uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: "Checkout tags"
+      # for get-version.sh, an unshallow git checkout with tags is needed.
+      run:  git fetch --tag
+
+    - name: "Set up Python"
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.7
+
+    - name: "Build python package"
+      run: |
+        pip install --user wheel
+        cd restapi
+        # sdist mangles around with version information.
+        # We replace ~pre with dev, as this will not be modified.
+        # (pre will be replaced with rc).
+        ../docs/manuals/source/get-version.sh > bareos_restapi/VERSION.txt
+        printf "Version: %s\n" $(cat bareos_restapi/VERSION.txt)
+        python setup.py sdist bdist_wheel
+
+    - name: "Create artifact"
+      # creating an artifact is not required for publishing to pypi.
+      uses: actions/upload-artifact@v2
+      with:
+        path: restapi/dist/
+
+    - name: "Publish to pypi.org"
+      uses: pypa/gh-action-pypi-publish@v1.4.2
+      with:
+        password: ${{ secrets.restapi_pypi_password }}
+        packages_dir: python-bareos/dist/

.github/workflows/publish_restapi_to_test-pypi.yml

@@ -0,0 +1,59 @@
+name: "bareos-restapi -> https://test.pypi.org/"
+
+#
+# build a bareos-restapi dev package
+# for every change in master,
+# affecting the relevant files.
+#
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - restapi/**
+      - .github/workflows/publish_restapi_to_test-pypi.yml
+
+jobs:
+  build-and-publish:
+    name: "Build bareos-restapi and publish it to https://test.pypi.org/"
+    runs-on: ubuntu-20.04
+
+    steps:
+    - name: "Checkout source"
+      uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: "Checkout tags"
+      # for get-version.sh, an unshallow git checkout with tags is needed.
+      run:  git fetch --tag
+
+    - name: "Set up Python"
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.7
+
+    - name: "Build python package"
+      run: |
+        pip install --user wheel
+        cd restapi
+        # sdist mangles around with version information.
+        # We replace ~pre with dev, as this will not be modified.
+        # (pre will be replaced with rc).
+        ../docs/manuals/source/get-version.sh > bareos_restapi/VERSION.txt
+        printf "Version: %s\n" $(cat bareos_restapi/VERSION.txt)
+        python setup.py sdist bdist_wheel
+
+    - name: "Create artifact"
+      # creating an artifact is not required for publishing to pypi.
+      uses: actions/upload-artifact@v2
+      with:
+        path: restapi/dist/
+
+    - name: "Publish to test.pypi.org"
+      uses: pypa/gh-action-pypi-publish@v1.4.2
+      with:
+        repository_url: https://test.pypi.org/legacy/
+        password: ${{ secrets.restapi_test_pypi_password }}
+        packages_dir: restapi/dist/

docs/manuals/source/DeveloperGuide/api.rst

@@ -432,63 +432,6 @@ Example of a JSON-RPC Error Response
    (``void UAContext::error_msg(const char *fmt, ...)``). Messages and
    the result so far will be part of the error response object.
 
-.. _sec:REST:
-
-REST API
---------
-
-Introduction
-~~~~~~~~~~~~
-This is an experimental and preliminary backend for development purposes. The endpoints are subject to review and may change in the future.
-
-It provides a REST API using `fastapi <https://fastapi.tiangolo.com/>`_ and python-bareos to connect to
-a Bareos director. It supports the :command:`configure add` commands to create configuration for clients, jobs, filesets and some more resources. It also provides endpoints to query job information and job control (i.e. start / restart jobs, trigger restores).
-
-Python3 is needed to run the REST API.
-
-Installation
-~~~~~~~~~~~~
-Use pip to install:
-:command:`pip3 install python-bareos-restapi`
-This will also install dependencies like fastapi, uvicorn and some more.
-
-
-Configuration
-~~~~~~~~~~~~~
-
-Configure your Bareos Server in :file:`api.ini` adapting these 3 lines of configuration:
-
-.. code-block:: cfg
-
-   [Director]
-   Name=bareos-dir
-   Address=127.0.0.1
-   Port=9101
-
-To configure the webserver uvicorn (e.g. adapt used network interfaces, ports), read the `uvicorn
-documentation <https://www.uvicorn.org/>`_. The default port is 8000 and the default interface is the loopback device.
-
-Start the backend server
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-:command:`uvicorn bareos-restapi:app --reload`
-
-Serve the Swagger UI to explore the REST API: `<http://127.0.0.1:8000/docs>`_
-Alternatively you can use the redoc format: `<http://127.0.0.1:8000/redoc>`_
-
-
-Browse
-~~~~~~
-
-The Swagger UI contains documentation and online-tests. Use "authorize" to connect to your Bareos director using a named console. Read here to learn how to configure
-a named console: :ref:`DirectorResourceConsole`
-
-The Swagger documentation also contains CURL statements for all available endpoints.
-
-Future work
-~~~~~~~~~~~
-
-The API will be extended by some methods provided by the Bareos console, that are not yet implemented. It is also planned to add delete / update options for configuration in the director and REST API. If you are interested in support and / or funding enhancements, please visit `<https://www.bareos.com>`_
 
 
 .. _sec:bvfs:
@@ -864,3 +807,71 @@ Example for directory browsing using bvfs
     1   1067    127 z Glnc IHo B GHH GHH A NVkY BAA BrA BaKDT2 BaKDT2 BaKDT2 A A C  928EB+EJGFtWD7wQ8bVjew  Incremental-0007    0
 
     # multiple versions of the file bareos-dir have been backed up.
+
+
+
+.. _sec:REST:
+
+REST API
+--------
+
+Introduction
+~~~~~~~~~~~~
+This is an experimental and preliminary backend for development purposes. The endpoints are subject to review and may change in the future.
+
+It provides a REST API using `fastapi <https://fastapi.tiangolo.com/>`_ and python-bareos to connect to
+a Bareos director. It supports the :command:`configure add` commands to create configuration for clients, jobs, filesets and some more resources. It also provides endpoints to query job information and job control (i.e. start / restart jobs, trigger restores).
+
+Python >= 3 is needed to run the REST API.
+
+Installation
+~~~~~~~~~~~~
+Use pip to install:
+
+.. code-block:: shell-session
+
+   pip install bareos-restapi
+
+
+This will also install dependencies like fastapi, uvicorn and some more.
+
+
+Configuration
+~~~~~~~~~~~~~
+
+Configure your Bareos Server in :file:`api.ini` adapting these 3 lines of configuration:
+
+.. code-block:: cfg
+
+   [Director]
+   Name=bareos-dir
+   Address=127.0.0.1
+   Port=9101
+
+To configure the webserver uvicorn (e.g. adapt used network interfaces, ports), read the `uvicorn
+documentation <https://www.uvicorn.org/>`_. The default port is 8000 and the default interface is the loopback device.
+
+Start the backend server
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: shell-session
+
+   uvicorn bareos_restapi:app --reload
+
+
+Serve the Swagger UI to explore the REST API: `<http://127.0.0.1:8000/docs>`_
+Alternatively you can use the redoc format: `<http://127.0.0.1:8000/redoc>`_
+
+
+Browse
+~~~~~~
+
+The Swagger UI contains documentation and online-tests. Use "authorize" to connect to your Bareos director using a named console. Read here to learn how to configure
+a named console: :ref:`DirectorResourceConsole`
+
+The Swagger documentation also contains CURL statements for all available endpoints.
+
+Future work
+~~~~~~~~~~~
+
+The API will be extended by some methods provided by the Bareos console, that are not yet implemented. It is also planned to add delete / update options for configuration in the director and REST API. If you are interested in support and / or funding enhancements, please visit `<https://www.bareos.com>`_

rest-api/README.md → restapi/README.md

@@ -14,37 +14,38 @@ a Bareos director.
 
 ### Installation
 
-Copy the rest-api directory to any place outside the source-tree and change into it.
-
-Change into the copied directory with _requirements.txt_, _bareos-restapi.py_ and _api.ini_
-* We recommend to create a dedicated Python environment for the installation:
+We recommend to create a dedicated Python environment for the installation in an own directory:
 
 ```
 python3 -m venv env
 # Activate the virtual environment inside the directory
 source env/bin/activate
 # Install dependencies into the virtual environment
-pip install -r requirements.txt
+pip install bareos-restapi
 ```
 
-Note: _requirements.txt_ contains a list of needed Python-modules, which will get installed by pip. The module _sslpsk==1.0.0_ is commented, because it requires an installed gcc and header files to be installed. Uncomment, if you want encrypted communication between the API and the Bareos director.
+Note: The optional module _sslpsk_ can be installed manually, if you want encrypted communication between the API and the Bareos director.
 
 ### Configuration
-Configure your Bareos Server in _api.ini_ adapting these 3 lines of configuration, so that it points to your director:
+
+The module directory contains a sample ini-file. Change into this directory (something like */lib/python3.x/site-packages/bareosRestapiModels* on most operating systems) and copy _api.ini.sample_ to _api.ini_ and adapt it to your director. Make sure to generate an own secret-key for the _JWT_ section.
+
+Your director configuration in _api.ini_ should look like:
 ```
 [Director]
 Name=bareos-dir
 Address=127.0.0.1
 Port=9101
 ```
 
-Note: you will need a _named console_ (user/password) to acces the Bareos director using this API. Read more about Consoles here:
+Note: you will need a *named console* (user/password) to acces the Bareos director using this API. Read more about Consoles here:
 https://docs.bareos.org/Configuration/Director.html#console-resource
 
-TODO: add possibility to connect to a choice of directors
 
 ### Start the backend server
 
+From inside the module directory run:
+
 ```
 uvicorn bareos-restapi:app --reload
 ```
@@ -63,4 +64,7 @@ The Swagger documentation also contains CURL statements for all available endpoi
 
 The API will be extended by some methods provided by the Bareos console, that are not yet implemented. It is also planned to add delete / update options for configuration in the director and REST API. If you are interested in support and / or funding enhancements, please visit https://www.bareos.com
 
-TODO: response model are not defined / documented yet.
+TODO: 
+- define and document response model
+- add possibility to connect to a choice of directors
+- add start-script with ini-file name as parameter