|
| 1 | +########## |
| 2 | +API levels |
| 3 | +########## |
| 4 | + |
| 5 | +python-gitlab works in three API layers, with different levels of convenience and control. |
| 6 | + |
| 7 | +High-level API - ``Gitlab`` managers and objects |
| 8 | +================================================ |
| 9 | + |
| 10 | +As shown in previous sections and examples, the high-level API interface wraps GitLab's API |
| 11 | +endpoints and makes them available from the ``Gitlab`` instance via managers that create |
| 12 | +objects you can manipulate. |
| 13 | + |
| 14 | +This is what most users will want to use, as it covers most of GitLab's API endpoints, and |
| 15 | +allows you to write idiomatic Python code when interacting with the API. |
| 16 | + |
| 17 | +Mid-level API - HTTP methods |
| 18 | +============================ |
| 19 | + |
| 20 | +.. danger:: |
| 21 | + |
| 22 | + At this point and lower, python-gitlab will no longer take care of URL-encoding and other |
| 23 | + transformations needed to correctly pass API parameter types. You have to construct these yourself. |
| 24 | + |
| 25 | +.. important:: |
| 26 | + |
| 27 | + If you've found yourself at this section because of an endpoint not yet implemented in |
| 28 | + the library - please consider opening a pull request implementing the resource or at |
| 29 | + least filing an issue so we can track progress. |
| 30 | + |
| 31 | + High-quality pull requests for standard endpoints that pass CI and include unit tests and |
| 32 | + documentation are easy to review, and can land quickly with monthly releases. If you ask, |
| 33 | + we can also trigger a new release, so you and everyone benefits from the contribution right away! |
| 34 | + |
| 35 | +Managers and objects call specific HTTP methods to fetch or send data to the server. These methods |
| 36 | +can be invoked directly to access endpoints not currently implemented by python-gitlab. This essentially |
| 37 | +gives you some level of usability for any endpoint the moment it is available on your GitLab instance. |
| 38 | + |
| 39 | +These methods can be accessed directly via the ``Gitlab`` instance (e.g. ``gl.http_get()``), or via an |
| 40 | +object's manager (e.g. ``project.manager.gitlab.http_get()``), if the ``Gitlab`` instance is not available |
| 41 | +in the current context. |
| 42 | + |
| 43 | +For example, if you'd like to access GitLab's `undocumented latest pipeline endpoint |
| 44 | +<https://gitlab.com/gitlab-org/gitlab/-/blob/5e2a61166d2a033d3fd1eb4c09d896ed19a57e60/lib/api/ci/pipelines.rb#L97>`__, |
| 45 | +you can do so by calling ``http_get()`` with the path to the endpoint: |
| 46 | + |
| 47 | +.. code-block:: python |
| 48 | +
|
| 49 | + >>> gl = gitlab.Gitlab(private_token=private_token) |
| 50 | + >>> |
| 51 | + >>> pipeline = gl.http_get("/projects/gitlab-org%2Fgitlab/pipelines/latest") |
| 52 | + >>> pipeline["id"] |
| 53 | + 449070256 |
| 54 | +
|
| 55 | +The available methods are: |
| 56 | + |
| 57 | +* ``http_get()`` |
| 58 | +* ``http_post()`` |
| 59 | +* ``http_put()`` |
| 60 | +* ``http_delete()`` |
| 61 | +* ``http_list()`` (a wrapper around ``http_get`` handling pagination, including with lazy generators) |
| 62 | + |
| 63 | +Low-level API - HTTP requests |
| 64 | +============================= |
| 65 | + |
| 66 | +At the lowest level, these HTTP methods call ``http_request()``, which performs the actual request. |
| 67 | + |
| 68 | +Although mostly designed for internal use in python-gitlab, this method can be invoked directly to |
| 69 | +call custom HTTP methods not currently implemented in the library - while still making use of all |
| 70 | +of the client's options and authentication methods. |
| 71 | + |
| 72 | +If, for whatever reason, you want to fetch allowed methods for an endpoint at runtime: |
| 73 | + |
| 74 | +.. code-block:: python |
| 75 | +
|
| 76 | + >>> gl = gitlab.Gitlab(private_token=private_token) |
| 77 | + >>> |
| 78 | + >>> response = gl.http_request("OPTIONS", "/projects") |
| 79 | + >>> response.headers["Allow"] |
| 80 | + 'OPTIONS, GET, POST, HEAD' |
| 81 | +
|
| 82 | +Check a file's size or if it exists in a project without fetching its entire content: |
| 83 | + |
| 84 | +.. code-block:: python |
| 85 | +
|
| 86 | + >>> gl = gitlab.Gitlab(private_token=private_token) |
| 87 | + >>> file_path = "/projects/gitlab-org%2Fgitlab/repository/files/Dangerfile" |
| 88 | + >>> |
| 89 | + >>> response = gl.http_request("HEAD", file_path, ref="master") |
| 90 | + >>> response.headers["x-gitlab-size"] |
| 91 | + '1548' |
0 commit comments