===============
 Low-level API
===============

The :mod:`gwosc.api` package provides low-level interface functions that handle direct requests to the GWOSC host.
Inside the `gwosc.api` package there are two modules, each one dealing with the 2 available versions of the API.

- :mod:`gwosc.api.v1`: Legacy API functions for backward compatibility
- :mod:`gwosc.api.v2`: Newer API functions with improved functionality

Given the sharp increase of detections in recent runs, we rebuilt our public API to cope with increased response length, and high-frequency requests.
API v2 introduces pagination and throttling features for all resources to guarantee scalability, and a smoother experience for developers and end users.
To learn more, visit https://gwosc.org/api/.

.. rubric:: Backward Compatibility
   :class: h2

For backward compatibility, the main :mod:`gwosc.api` module imports all functions from the v1 API. This means existing code that imports from :mod:`gwosc.api` will continue to work without changes.

.. automodule:: gwosc.api
   :members:
   :undoc-members:
   :show-inheritance:

.. rubric:: API v2 (Current)
   :class: h2

.. automodule:: gwosc.api.v2
   :members:
   :undoc-members:
   :show-inheritance:
   :exclude-members: DEFAULT_URL, JSON_CACHE, LARGE_NUM_PAGES_WARN

.. rubric:: API v1 (Legacy)
   :class: h2

.. automodule:: gwosc.api.v1
   :members:
   :undoc-members:
   :show-inheritance:
   :exclude-members: DEFAULT_URL, JSON_CACHE
