docs(api): describe use of lower-level methodsdocs/lower-level-api

1 files changed, 91 insertions, 0 deletions

diff --git a/docs/api-levels.rst b/docs/api-levels.rst
new file mode 100644
index 0000000..23150e9
--- /dev/null
+++ b/docs/api-levels.rst
@@ -0,0 +1,91 @@
+##########
+API levels
+##########
+
+python-gitlab works in three API layers, with different levels of convenience and control.
+
+High-level API - ``Gitlab`` managers and objects
+================================================
+
+As shown in previous sections and examples, the high-level API interface wraps GitLab's API
+endpoints and makes them available from the ``Gitlab`` instance via managers that create
+objects you can manipulate.
+
+This is what most users will want to use, as it covers most of GitLab's API endpoints, and
+allows you to write idiomatic Python code when interacting with the API.
+
+Mid-level API - HTTP methods
+============================
+
+.. danger::
+
+   At this point and lower, python-gitlab will no longer take care of URL-encoding and other
+   transformations needed to correctly pass API parameter types. You have to construct these yourself.
+
+.. important::
+
+   If you've found yourself at this section because of an endpoint not yet implemented in
+   the library - please consider opening a pull request implementing the resource or at
+   least filing an issue so we can track progress.
+
+   High-quality pull requests for standard endpoints that pass CI and include unit tests and
+   documentation are easy to review, and can land quickly with monthly releases. If you ask,
+   we can also trigger a new release, so you and everyone benefits from the contribution right away!
+
+Managers and objects call specific HTTP methods to fetch or send data to the server. These methods
+can be invoked directly to access endpoints not currently implemented by python-gitlab. This essentially
+gives you some level of usability for any endpoint the moment it is available on your GitLab instance.
+
+These methods can be accessed directly via the ``Gitlab`` instance (e.g. ``gl.http_get()``), or via an
+object's manager (e.g. ``project.manager.gitlab.http_get()``), if the ``Gitlab`` instance is not available
+in the current context.
+
+For example, if you'd like to access GitLab's `undocumented latest pipeline endpoint
+<https://gitlab.com/gitlab-org/gitlab/-/blob/5e2a61166d2a033d3fd1eb4c09d896ed19a57e60/lib/api/ci/pipelines.rb#L97>`__,
+you can do so by calling ``http_get()`` with the path to the endpoint:
+
+.. code-block:: python
+
+    >>> gl = gitlab.Gitlab(private_token=private_token)
+    >>>
+    >>> pipeline = gl.http_get("/projects/gitlab-org%2Fgitlab/pipelines/latest")
+    >>> pipeline["id"]
+    449070256
+
+The available methods are:
+
+* ``http_get()``
+* ``http_post()``
+* ``http_put()``
+* ``http_delete()``
+* ``http_list()`` (a wrapper around ``http_get`` handling pagination, including with lazy generators)
+
+Low-level API - HTTP requests
+=============================
+
+At the lowest level, these HTTP methods call ``http_request()``, which performs the actual request.
+
+Although mostly designed for internal use in python-gitlab, this method can be invoked directly to
+call custom HTTP methods not currently implemented in the library - while still making use of all
+of the client's options and authentication methods.
+
+If, for whatever reason, you want to fetch allowed methods for an endpoint at runtime:
+
+.. code-block:: python
+
+    >>> gl = gitlab.Gitlab(private_token=private_token)
+    >>>
+    >>> response = gl.http_request("OPTIONS", "/projects")
+    >>> response.headers["Allow"]
+    'OPTIONS, GET, POST, HEAD'
+
+Check a file's size or if it exists in a project without fetching its entire content:
+
+.. code-block:: python
+
+    >>> gl = gitlab.Gitlab(private_token=private_token)
+    >>> file_path = "/projects/gitlab-org%2Fgitlab/repository/files/Dangerfile"
+    >>>
+    >>> response = gl.http_request("HEAD", file_path, ref="master")
+    >>> response.headers["x-gitlab-size"]
+    '1548'