== ARK API - Documentation ==

NOTE - Variables are marked by { }!

/ark:/{NAAN}
    /<namespace>
        * [GET] - List ARKs in the namespace
    /<namespace>/<name>
        * [GET] - Get information about an ARK (incl. metadata)
    /<namespace>/<name> - POST parameters: 'Metadata'
        * [POST] - Create a new ARK
          * Metadata (mandatory):
            * who
            * what
            * when
            * where
            * how
            * _t
          * For further information regarding mandatory metadata: https://n2t.net/e/n2t_apidoc.html#identifier-metadata
        * [PATCH] - Update ARK information
          * Available parameters (POST data):
            * tombstone - true or false
              * The tombstone status of the ARK (ARK still active / ARK buried)
            * namespace - Name of the namespace
              * Transfer an ARK to another namespace
            * email - User email
              * Change the owner of the ARK to another user
            * private - true or false
              * Update whether the ARK is available to the public or only to the owner
        * [DELETE] - Delete ARKs that are not older than fifteen (15) minutes

/user
    * [GET] - List all users
    * [PATCH] - Update information about YOUR account
      * POST parameters: 'name', 'newemail', 'password', 'status'
        * Example for admin impersonation (introducing the 'user' POST parameter):
          $ curl -sX PATCH localhost:11811/user/EMAIL -d 'user=EMAIL&name=NEWNAME' -b cookies
    /<email>
        * [GET] - Get information about a specific user
    /<email> - POST parameters: 'name' / 'password'
        * [POST] - Create a new user
    /<email>/delete
        * [DELETE] - Delete your own account (<email> is your own email address for confirmation!)
          * Users need to assure, that they transfer their admin privileges to other members of a namespace.
            This can be done using the PATCH method in the /namespaceuser endpoint.
            The namespace will possibly be left without an active admin without doing that.

/namespace
    * [GET] - List all namespaces
    /<namespace>
        * [GET] - Get information about a namespace  # If the user is part of the namespace, also list the namespace members
        * [DELETE] - Delete a namespace (user needs to be an admin)
    /<namespace> - POST parameters: 'desc' (Namespace description)
        * [POST] - Create a new namespace with the current user as admin

/namespaceuser
    * [GET] - List usage of the API endpoint?
    /<namespace> - POST parameters: 'email'
        * [POST] - Add the specified user to a namespace
        * [DELETE] - Remove the specified user from the namespace
    /<namespace> - POST parameters: 'email' / 'admin'
        * [POST] - Add the specified user as an admin to the namespace
    /<namespace>/<role> - POST parameters: 'email'
        * [PATCH] - Set the permission of a namespace user

/login
    * [POST] - Login with own credentials
        * Example:
            * $ curl -X POST {URL}/login --user '{USER}:{PASSWORD}' -c {COOKIE_FILE}
        * The cookie saved in the COOKIE_FILE will be your session cookie. It is valid for 15 minutes.
            * After 15 minutes you'll need to reauthenticate by using the /login endpoint!
    * How do I use the session cookie for authentication?
        * Example - Namespace creation:
            * $ curl -X POST {URL}/namespace/{NAMESPACE} -d 'desc={DESCRIPTION}' -b {COOKIE_FILE}
        * For more information see:
            * $ man curl | grep "\--cookie"

/token
    * [POST] - Create a token for the current user
    * [DELETE] - Delete the token of the current user
    * The /token endpoint returns the generated token upon success.
      You can then use it for authentication by using one of the following methods:
      * $ ... -b 'tokenid={TOKEN}'
      * Write it to a cookie file (like the session id) and use it with '-b {COOKIE_FILE}'

== Example usage ==

To supply POST data via curl:
$ curl -X POST -d '{VARIABLE}={VALUE}'

To supply multiple POST values via curl:
$ curl -X POST -d '{VARIABLE1}={VALUE1}&{VARIABLE2}={VALUE2}'

Multiple keys and values can be appended by using the '&' parameter.

== Examples for testing ==

Use jq to have prettified/formatted JSON output and filtering capabilities
# https://stedolan.github.io/jq/
$ curl https://ark-test.rd.ruhr-uni-bochum.de/ | jq