Skip to content

Fix doc feedback issues for the HTTP client #4034

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 8, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
local http_client = require('http.client')
local response = http_client.get('https://httpbin.org/get')
print('Status: '..response.status..' '.. response.reason)

local luatest = require('luatest')
local test_group = luatest.group()
test_group.test_returns_status = function()
luatest.assert_equals(response.status, 200)
end
39 changes: 34 additions & 5 deletions doc/reference/reference_lua/http.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,26 +12,55 @@ The HTTP client uses the `libcurl <https://curl.haxx.se/libcurl/>`_ library unde
takes into account the `environment variables <https://curl.haxx.se/libcurl/c/libcurl-env.html>`_ libcurl understands.


.. _http_client_instance:

HTTP client instance
--------------------

.. _http_client_instance_default:

Default client
~~~~~~~~~~~~~~

The ``http.client`` submodule provides the default HTTP client instance:

.. literalinclude:: /code_snippets/test/http_client/default_client_get_test.lua
:language: lua
:lines: 1

In this case, you need to make requests using the dot syntax, for example:

.. literalinclude:: /code_snippets/test/http_client/default_client_get_test.lua
:language: lua
:lines: 2


.. _creating_client:

Creating a client
-----------------
~~~~~~~~~~~~~~~~~

To create an HTTP client, call the :ref:`http.client.new() <http-new>` function:
If you need to configure specific HTTP client options, use the :ref:`http.client.new() <http-new>` function to create the client instance:

.. literalinclude:: /code_snippets/test/http_client/get_test.lua
:language: lua
:lines: 1

Optionally, this function can accept specific client configuration options.
In this case, you need to make requests using the colon syntax, for example:

.. literalinclude:: /code_snippets/test/http_client/get_test.lua
:language: lua
:lines: 2

All the examples in this section use the HTTP client created using ``http.client.new()``.


.. _making_requests:

Making requests
---------------

After :ref:`creating the client <creating_client>`, you can make HTTP requests.
The :ref:`client instance <http_client_instance>` enables you to make HTTP requests.

.. _request_http_method:

Expand Down Expand Up @@ -685,7 +714,7 @@ client_object

* ``active_requests`` -- the number of currently executing requests
* ``sockets_added`` -- the total number of sockets added into an event loop
* ``sockets_deleted`` -- the total number of sockets from an event loop
* ``sockets_deleted`` -- the total number of sockets deleted from an event loop
* ``total_requests`` -- the total number of requests
* ``http_200_responses`` -- the total number of requests that returned HTTP ``200 OK`` responses
* ``http_other_responses`` -- the total number of requests that returned non-``200 OK`` responses
Expand Down