metax-access
============

metax-access is a Python module used to communicate with Metax. It contains
many utility functions, which help making HTTP requests to Metax.

Installation
------------

If you're on CentOS, you can install Python interpreter and git by running the
following command in terminal:

.. code-block:: console

    $ sudo yum install -y python3 git

Clone the metax-access repository to your machine by running:

.. code-block:: console

    $ git clone https://github.com/Digital-Preservation-Finland/metax-access.git

Change to the newly created directory and install metax-access by running:

.. code-block:: console

    $ cd metax-access
    $ make github
    $ source venv/bin/activate

:code:`make github` runs github target in the Makefile, which installs
metax-access in a virtual environment and creates a default config file
~/.metax.cfg. :code:`source venv/bin/activate` activates the newly created
virtual environment. Finally, edit the ~/.metax.cfg file with editor of your
choice, e.g.:

.. code-block:: console

    $ vi ~/.metax.cfg

to look like::

    [metax]
    host=https://metax.fairdata.fi
    user=
    password=
    token=YOUR_PERSONAL_TOKEN

The token can be acquired from https://metax.fairdata.fi/secure.

Usage
-----

metax-access has a command-line user interface, which is used with the command
:code:`metax_access`. Try:

.. code-block:: console

    $ metax_access --help

and:

.. code-block:: console

    $ metax_access COMMAND --help

where COMMAND is one of the provided subcommands: ``post``, ``get``,
``delete`` or ``patch``.
These commands can be used to send POST, GET, DELETE or PATCH requests to
Metax correspondingly. The requests are sent to specific Metax resources, which
are:

    - file
    - dataset
    - contract

For example, a GET request to dataset with identifier DATASET_IDENTIFIER can be
sent with command:

.. code-block:: console

    $ metax_access get dataset DATASET_IDENTIFIER

Creating and modifying Metax datasets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Let's go through a practical example of:

    1. Fetching a minimal dataset template from Metax.
    2. Modifying the template dataset and POSTing it to Metax.
    3. Editing the dataset with a PATCH request.
    4. Deleting the dataset.

GET the minimal dataset template and save it to dataset_template.json with
the command:

.. code-block:: console

    $ metax_access -o dataset_template.json get template dataset

Modify the template dataset with the editor of your choice, e.g.:

.. code-block:: console

    $ vi dataset_template.json

If you are using the Pre-Ingest File Storage API instead of IDA, you should at
the very least change the data_catalog to:
:code:`urn:nbn:fi:att:data-catalog-pas`.  Once you have edited the template
dataset, you can POST it to Metax with the command:

.. code-block:: console

    $ metax_access post dataset dataset_template.json

Datasets that have been POSTed to Metax can be edited with PATCH requests.
Start by writing the dataset into a file:

.. code-block:: console

    $ metax_access -o dataset.json get dataset DATASET_IDENTIFIER

Edit the created file :code:`dataset.json` to fix the mistakes and send a
PATCH request with the command:

.. code-block:: console

    $ metax_access patch dataset DATASET_IDENTIFIER dataset.json

Finally, if you want to remove your datasets from metax, you can send a DELETE
request:

.. code-block:: console

    $ metax_access delete dataset DATASET_IDENTIFIER