API Usage
=========

There are currently **5** different API endpoints used by the front-end of the application.
These can all be found in ``client/src/hooks``.

They all use ``axios`` for the requests, and each implements a different function.
Helper functions for transforming data and the global types used can be found in ``client/utils``.

API Hooks
---------

1. **useFetchIPData**

   This hook provides the user’s query (IP or domain name) as a payload to the backend.

   It performs a **POST** request to the backend to measure the given NTP server.
   If the query is a domain name, the result includes all NTP servers measured from that domain name.
   If it's an IP, only that specific NTP server is measured.

   It parses the JSON received using the method ``transformJSONDataToNTPData``.

   It returns a **5-tuple**:

   +------------------+--------------------------------------------------------------+
   | Return value     | Description                                                  |
   +==================+==============================================================+
   | ``data``         | An array of NTP results                                      |
   +------------------+--------------------------------------------------------------+
   | ``loading``      | ``boolean`` indicating if the measurement is ongoing         |
   +------------------+--------------------------------------------------------------+
   | ``error``        | Error object if one occurred                                 |
   +------------------+--------------------------------------------------------------+
   | ``httpStatus``   | The HTTP status of the request                               |
   +------------------+--------------------------------------------------------------+
   | ``fetchData``    | A function to initiate the POST request                      |
   +------------------+--------------------------------------------------------------+

2. **useFetchHistoricalIPData**

   This hook fetches data over a specific period for a given server.

   It performs a **GET** request to the backend. The server can be either an IP or domain name.
   Start and end times must be in ISO8601 format.

   It also uses ``transformJSONDataToNTPData``.

   It returns a **4-tuple**:

   +------------------+--------------------------------------------------------------+
   | Return value     | Description                                                  |
   +==================+==============================================================+
   | ``data``         | An array of NTP results                                      |
   +------------------+--------------------------------------------------------------+
   | ``loading``      | ``boolean`` indicating if the fetch is ongoing               |
   +------------------+--------------------------------------------------------------+
   | ``error``        | Error object if one occurred                                 |
   +------------------+--------------------------------------------------------------+
   | ``fetchData``    | A function to initiate the GET request                       |
   +------------------+--------------------------------------------------------------+

3. **triggerRipeMeasurement**

   This hook sends a trigger to start a RIPE measurement.

   It performs a **POST** request to the backend with the server as payload.
   The backend responds with the measurement ID and the vantage point's IP.

   It returns a **4-tuple**:

   +------------------+--------------------------------------------------------------+
   | Return value     | Description                                                  |
   +==================+==============================================================+
   | ``data``         | The response as a ``RIPEResp`` object                        |
   +------------------+--------------------------------------------------------------+
   | ``loading``      | ``boolean`` indicating if the trigger is being processed     |
   +------------------+--------------------------------------------------------------+
   | ``error``        | Error object if one occurred                                 |
   +------------------+--------------------------------------------------------------+
   | ``fetchData``    | A function to initiate the POST request                      |
   +------------------+--------------------------------------------------------------+

4. **useFetchRipeData**

   This hook fetches RIPE measurement data via polling.

   RIPE sends results in parts, so polling is used to retrieve updates. If the RIPE measurement isn't ready,
   the hook handles HTTP 405 and retries after a delay. The polling stops if:
   - An error occurs
   - Measurement completes
   - It times out
   - A new measurement begins

   It returns a **3-tuple**:

   +--------------+-----------------------------------------------------------------+
   | Return value | Description                                                     |
   +==============+=================================================================+
   | ``result``   | An array of RIPE results                                        |
   +--------------+-----------------------------------------------------------------+
   | ``status``   | A status string: ``"pending" | "partial_results" | "complete"   |
   |              | | "timeout" | "error"``                                         |
   +--------------+-----------------------------------------------------------------+
   | ``error``    | Error object if one occurred                                    |
   +--------------+-----------------------------------------------------------------+

5. **useIpInfo**

   This hook fetches geolocation data for an IP without contacting the backend.

   It uses ``ip-api`` to retrieve coordinates and country code. Used for NTP servers and the vantage point.

   The result is stored in an ``IpInfoData`` object:

   - ``coordinates``: a tuple ``[number, number]``
   - ``country_code``: a ``string``

   Note: If the IP is private, ``coordinates`` will be ``[undefined, undefined]``.

   It returns a **5-tuple**:

   +------------------+----------------------------------------------------------------+
   | Return value     | Description                                                    |
   +==================+================================================================+
   | ``data``         | Geolocation data as ``IpInfoData``                             |
   +------------------+----------------------------------------------------------------+
   | ``loading``      | ``boolean`` indicating if the fetch is ongoing                 |
   +------------------+----------------------------------------------------------------+
   | ``error``        | Error object if one occurred                                   |
   +------------------+----------------------------------------------------------------+
   | ``fetchData``    | A function to initiate the GET request                         |
   +------------------+----------------------------------------------------------------+
   | ``clearIP``      | A function to reset the internal state of ``data``             |
   +------------------+----------------------------------------------------------------+