.. _object_notes:

Method: Object Notes
--------------------

Each object can carry an encrypted free-text note. Notes are encrypted with the
vault's key and stored alongside the object. Reading notes requires vault
read access; writing requires vault write access.

.. note::
   Notes are stored under the ``/notes`` route but read back via ``/objectattr``.
   These two endpoints together form the full read/write interface for notes.

.. _notes_write:

Write (create or update) a Note
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Description
^^^^^^^^^^^

Creates or replaces the encrypted note on an object. The note text must be
Base64-encoded by the caller before sending. An empty string clears the note.

URL Syntax
^^^^^^^^^^

/api/{version}/notes/:object-id

HTTP Method
^^^^^^^^^^^

POST

Successful HTTP Response
^^^^^^^^^^^^^^^^^^^^^^^^^

200

Parameters
^^^^^^^^^^

+----------------+-----------------------------------+----------------+---------+-----------+---------------------------------------+
| Parameter name | Description                       | Parameter type | Type    | Mandatory | Comment                               |
+================+===================================+================+=========+===========+=======================================+
| X-Http-Token   | StoredSafe token                  | HTTP Header    | String  | Yes       |                                       |
+----------------+-----------------------------------+----------------+---------+-----------+---------------------------------------+
| object-id      | Object ID                         | URL-parameter  | Integer | Yes       |                                       |
+----------------+-----------------------------------+----------------+---------+-----------+---------------------------------------+
| notes          | Note text, Base64-encoded         | JSON-encoded   | String  | Yes       | Send empty string to clear the note   |
+----------------+-----------------------------------+----------------+---------+-----------+---------------------------------------+

Response Attributes
^^^^^^^^^^^^^^^^^^^

+---------------------+--------------------------------------------------+---------+
| Attribute           | Description                                      | Type    |
+=====================+==================================================+=========+
| CALLINFO.status     | SUCCESS or FAIL                                  | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.token      | StoredSafe token to be used in subsequent calls  | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.handler    | Handler used                                     | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errors     | Number of errors                                 | Integer |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errorcodes | Number of error codes                            | Integer |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.general    | Status information                               | Array   |
+---------------------+--------------------------------------------------+---------+

Example
^^^^^^^

Save the note "Remember to rotate this key annually." on object 489.

**Request**

::

    POST /api/1.0/notes/489
    X-Http-Token: your_storedsafe_token
    Content-Type: application/json
    {
        "notes": "UmVtZW1iZXIgdG8gcm90YXRlIHRoaXMga2V5IGFubnVhbGx5Lg=="
    }

**Response**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": ["Notes saved"],
            "handler": "NotesHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token"
        },
        "DATA": { ... },
        "HEADERS": { ... },
        "PARAMS": []
    }

.. _notes_read:

Read a Note
~~~~~~~~~~~

Description
^^^^^^^^^^^

Retrieves and decrypts the note stored on an object. Uses the ``/objectattr``
endpoint with ``attr=notes``.

URL Syntax
^^^^^^^^^^

/api/{version}/objectattr/:object-id

HTTP Method
^^^^^^^^^^^

GET

Successful HTTP Response
^^^^^^^^^^^^^^^^^^^^^^^^^

200

Parameters
^^^^^^^^^^

+----------------+-----------------------------------+----------------+---------+-----------+
| Parameter name | Description                       | Parameter type | Type    | Mandatory |
+================+===================================+================+=========+===========+
| X-Http-Token   | StoredSafe token                  | HTTP Header    | String  | Yes       |
+----------------+-----------------------------------+----------------+---------+-----------+
| object-id      | Object ID                         | URL-parameter  | Integer | Yes       |
+----------------+-----------------------------------+----------------+---------+-----------+
| attr           | Must be the string ``notes``      | URL-parameter  | String  | Yes       |
+----------------+-----------------------------------+----------------+---------+-----------+

Response Attributes
^^^^^^^^^^^^^^^^^^^

+---------------------+--------------------------------------------------+---------+
| Attribute           | Description                                      | Type    |
+=====================+==================================================+=========+
| CALLINFO.status     | SUCCESS or FAIL                                  | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.token      | StoredSafe token to be used in subsequent calls  | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.handler    | Handler used                                     | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errors     | Number of errors                                 | Integer |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errorcodes | Number of error codes                            | Integer |
+---------------------+--------------------------------------------------+---------+
| NOTES               | Decrypted note text (plain string)               | String  |
+---------------------+--------------------------------------------------+---------+

Example
^^^^^^^

Read the note on object 489.

**Request**

::

    GET /api/1.0/objectattr/489?attr=notes
    X-Http-Token: your_storedsafe_token

**Response**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "ObjectattrHandler",
            "status": "SUCCESS",
            "token": "rotated_storedsafe_token"
        },
        "DATA": { ... },
        "HEADERS": { ... },
        "NOTES": "Remember to rotate this key annually.",
        "PARAMS": []
    }