##############################
Using the REST API for PixStor
##############################

Background
==========

The PixStor Management REST API uses an :doc:`object model <orm>` which abstraction over the underlying file system.

Consequently, there is not a one-to-one mapping between the REST API and PixStor objects, such as filesets.

This page lays-out how PixStor objects and operations can be mapped to nearest equivalent REST API methods.

This is a relatively high level description, ignoring things like authentication. For a more detailed look at the REST API, see :doc:`rest`

List Filesystems
================

Filesystems roughly correspond to Native Exposers

.. code::

    GET /exposers/?where={"type":"gpfsnative"}

List Filesets
=============

Filesets correspond to Spaces

.. code::

    GET /spaces/

List filesets in a filesystem
-----------------------------

.. code::

    GET /spaces/?where={"exposers.filesystem":"mmfs1"}

This won't return unlinked filesets, or filesets excluded by the apconfig setting ``arcapix.management.filesets.exclude``

List Snapshots
==============

.. code::

    GET /snapshots/

List filesystem global snapshots
--------------------------------

.. code::

    GET /snapshots/?where={"exposer.filesystem":"mmfs1"}

List fileset snapshots
----------------------

.. code::

    GET /snapshots/?where={"space.name":"projects"}

NOTE: This is search by space name, not fileset name

Typically, the fileset name will be the space name prefixed with target pool name e.g. ``sas1-projects``

List NFS Shares
===============

.. code::

    GET /exposers/?where={"type":"nfs"}

List Samba Shares
=================

.. code::

    GET /exposers/?where={"type":"cifs"}

Create a Fileset
================

For a more detailed discussion of creating a fileset (space), see :doc:`space-walkthru`

In the PixStor Admin UI, there are 3 types of fileset - Independent, Dependent, and Templated

In the REST API, there are just dependent and independent filesets, both of which can have templates installed.

Settings
--------

Name
^^^^

Name of the space. Note that the fileset will be the space name prefixed with the name of the placement pool.

So if the space name is ``projects`` and the placement pool is ``sas1``, then the fileset will be named ``sas1-projects```

Profile
^^^^^^^

The profile determines the filesystem that the fileset belongs to, and which pool the fileset data is allocated to.

You can create your own profile, or you can use one of the predefined ones.
For every filesystem and data pool, there is a :ref:`corresponding <placement_rules>` profile.
There is also a special 'default' profile for each filesystem, which corresponds to whatever the filesystem default placement pool is.

These predefined profiles are named like ``{filesystem}-{pool}``.
So to create a fileset in ``mmfs1``, allocated to pool ``sas1``, we need to lookup the id for the corresponding profile

.. code::

    GET /profiles/?where={"name":"mmfs1-sas1"}

Templates
^^^^^^^^^

A fileset can optionally have one or more templates applied to it.

A template is a pre-defined directory structure with permissions and optional dependent filesets.

Exposers
^^^^^^^^

GPFS native exposers roughly correspond to filesystems. 
However, as previously mentioned, the filesystem that a space (fileset) is assigned to is determined by it's profile.

The exposer is optional, but if provided it must be the GPFS native exposer corresponding the the profile filesystem.

.. code::

    GET /exposers/?where={"type":"gpfsnative","name":"mmfs1"}

If the exposer is provided, the fileset will be linked, if not it will be unlinked

Relative Path
^^^^^^^^^^^^^

The relative path defines where the fileset will be linked if an exposer is provided

For example, if the native exposer has mountpoint ``/mmfs1`` and the space has relative path ``projects``,
then the fileset will be linked at ``/mmfs1/projects``

Size
^^^^

If a size is specified, a block quota will be created for the fileset.
The hard limit will be the specified size, and the soft limit will be 90% of the size.

If a size if not specified, no quota will be applied.

Extras
^^^^^^

There are various additional settings which can be provided via extras:

``gpfs.fileset.dependent``

Indicates whether the fileset should dependent or independent.

An independent fileset has its own inodespace, while a dependent fileset belongs to another fileset's inodespace

``gpfs.fileset.inodespace``

The inodespace the fileset should be assigned to.

This only has meaning for dependent filesets. Independent fileset always belong to inodespace 0

If not provided, the inodespace for dependent filesets will be inferred from the link path (via the space's exposer and relative path).

``gpfs.fileset.maxinodes``

The maximum inodes allocation of the corresponding fileset.

If not provided, a default value will be used. For PixStor Management 0.3 and earlier, the default values was 20,000.
As of PixStor Management 0.4, this default is configurable via the :doc:`apconfig <configuration>`
setting ``arcapix.management.filesets.maxinodes``

``gpfs.fileset.allocinodes``

The number of inodes allocated to the corresponding fileset. allocinodes must be less than maxinodes.

If not provided, a default value will be used. For PixStor Management 0.3 and earlier, the default values was 10,000.
As of PixStor Management 0.4, this default is configurable via the :doc:`apconfig <configuration>`
setting ``arcapix.management.filesets.allocinodes``

.. note::

    Inode limits can't be set for dependent filesets. If provided, these settings will be ignored.

Templated Independent Fileset
-----------------------------

.. code::

    POST /spaces/
    {
        "template": {
            "data": [
            {
                "name": "name",
                "value": "projects"
            },
            {
                "name": "profile",
                "value": "/profiles/116cca6e-21cf-4ee0-b950-d37eca6d29d7"
            },
            {
                "name": "templates",
                "value": "/templates/397efad5-4ab5-4b01-8955-954360acffc7"
            },
            {
                "name": "exposers",
                "value": "/exposers/0f34e6c4-880d-479f-86bd-4de952697cdf"
            },
            {
                "name": "relativepath",
                "value": "projects"
            },
            {
                "name": "size",
                "value": 4294967296
            },
            {
                "name": "extras",
                "value": {
                    "gpfs.fileset.allocinodes": 102400,
                    "gpfs.fileset.maxinodes": 204800
                }
            }
            ]
        }
    }

Dependent Fileset
-----------------

.. code::

    POST /spaces/
    {
        "template": {
            "data": [
            {
                "name": "name",
                "value": "assets"
            },
            {
                "name": "profile",
                "value": "/profiles/116cca6e-21cf-4ee0-b950-d37eca6d29d7"
            },
            {
                "name": "exposers",
                "value": "/exposers/0f34e6c4-880d-479f-86bd-4de952697cdf"
            },
            {
                "name": "relativepath",
                "value": "projects/assets"
            },
            {
                "name": "extras",
                "value": {
                    "gpfs.fileset.dependent": true,
                    "gpfs.fileset.inodespace": 13
                }
            }
            ]
        }
    }

Change fileset link path
========================

.. code::

    PATCH /spaces/e8919907-f896-4e89-883c-2ae68ad5b7b3
    {
        "template": {
            "data": [
            {
                "name": "relativepath",
                "value": "projects.backup"
            }
            ]
        }
    }

Change fileset quota
====================

.. code::

    PATCH /spaces/e8919907-f896-4e89-883c-2ae68ad5b7b3
    {
        "template": {
            "data": [
            {
                "name": "size",
                "value": 8589934592
            }
            ]
        }
    }

Unset quota
-----------

.. code::

    PATCH /spaces/e8919907-f896-4e89-883c-2ae68ad5b7b3
    {
        "template": {
            "data": [
            {
                "name": "size",
                "value": 0
            }
            ]
        }
    }

Create a Snapshot
=================

Global snapshot
---------------

To create a global snapshot, you create a snapshot of the gpfs native exposer corresponding to the filesystem you want to snapshot

.. code::

    GET /exposers/?where={"type":"gpfsnative","name":"mmfs1"}

.. code::

    POST /snapshots/
    {
        "template": {
            "data": [
            {
                "name": "name",
                "value": "global-snapshot1"
            },
            {
                "name": "type",
                "value": "gpfsnativeexposersnapshot",
            },
            {
                "name": "exposer",
                "value": "/exposers/b7a39fd6-436e-469c-83c0-16f8cc7d7dd1"
            }
            ]
        }
    }

Fileset snapshot
----------------

Similarly, to create a fileset snapshot, you create a snapshot of the space corresponding to the fileset you want to snapshot

.. code::

    POST /snapshots/
    {
        "template": {
            "data": [
            {
                "name": "name",
                "value": "projects.1565013620"
            },
            {
                "name": "type",
                "value": "gpfsspacesnapshot",
            },
            {
                "name": "space",
                "value": "/spaces/9a54fd89-c56e-46c9-bd16-e6d6d3d91e12"
            }
            ]
        }
    }

.. note::

    Snapshots cannot be created for dependent filesets

Create an NFS Share
===================

``readonly`` is the only 'first class' setting. All other valid nfs settings can be passed via ``extras``

.. code::

    POST /exposers/
    {
        "template": {
            "data": [
            {
                "name": "sharepath",
                "value": "/mmfs1/data"
            },
            {
                "name": "client",
                "value": "*"
            },
            {
                "name": "type",
                "value": "nfs"
            },
            {
                "name": "readonly",
                "value": true
            },
            {
                "name": "extras",
                "value": {
                    "no_root_squash": true,
                    "secure": true
                }
            }
            ]
        }
    }

Create a Samba Share
====================

``readonly`` and ``visible`` are 'first class' settings. All other valid samba settings can be passed via ``extras``

``visible`` is equivalent to the samba ``browsable`` setting

.. code::

    POST /exposers/
    {
        "template": {
            "data": [
            {
                "name": "name",
                "value": "some_data"
            },
            {
                "name": "sharepath",
                "value": "/mmfs1/data"
            }
            {
                "name": "type",
                "value": "cifs"
            },
            {
                "name": "visible",
                "value": true
            },
            {
                "name": "readonly",
                "value": true
            },
            {
                "name": "extras",
                "value": {
                    "gpfs:hsm": true,
                    "guest ok": false
                }
            },
            ]
        }
    }