Merge pull request #9260 from nextcloud/enhancement/dev-http-client-docs

Add developer documentation for the HTTP client

developer_manual/digging_deeper/http_client.rst

@@ -0,0 +1,134 @@
+===========
+HTTP Client
+===========
+
+Nextcloud comes with a simple HTTP client that can be used to send requests to other web servers. This client follows Nextcloud's configuration, security restrictions and proxy settings.
+
+Acquiring a HTTP Client
+-----------------------
+
+HTTP client instances are built using the client service `factory <https://en.wikipedia.org/wiki/Factory_(object-oriented_programming)>`_ ``IClientService``. The factory can be :ref:`injected<dependency-injection>` into any app class:
+
+.. code-block:: php
+
+    <?php
+
+    use OCP\Http\IClientService;
+
+    class MyRemoteServerIntegration {
+        private IClientService $clientService;
+        public function __construct(IClientService $clientService) {
+            $this->clientService = $clientService;
+        }
+
+        public function downloadNextcloudWebsite(): void {
+            $client = $this->clientService->newClient();
+            $response = $client->get('https://nextcloud.com');
+        }
+    }
+
+HEAD request
+------------
+
+.. code-block:: php
+
+    <?php
+
+    $client = $this->clientService->newClient();
+    $response = $client->head('https://nextcloud.com');
+
+
+GET request
+-----------
+
+.. code-block:: php
+
+    <?php
+
+    $client = $this->clientService->newClient();
+    $response = $client->get('https://nextcloud.com');
+
+POST request
+------------
+
+.. code-block:: php
+
+    <?php
+
+    $client = $this->clientService->newClient();
+    $response = $client->post('https://api.domain.tld/pizza', [
+        'headers' => [
+            'Accept' => 'application/json',
+            'Content-Type' => 'application/json',
+        ],
+        'body' => json_encode([
+            'toppings' => [
+                'cheese',
+                'pineapple',
+            ],
+        ])
+    ]);
+    $pizza = json_decode($response, true);
+
+PUT request
+-----------
+
+.. code-block:: php
+
+    <?php
+
+    $client = $this->clientService->newClient();
+    $response = $client->put('https://api.domain.tld/pizza/42', [
+        'headers' => [
+            'Accept' => 'application/json',
+            'Content-Type' => 'application/json',
+        ],
+        'body' => json_encode([
+            'toppings' => [
+                'cheese',
+                'pineapple',
+            ],
+        ])
+    ]);
+    $pizza = json_decode($response, true);
+
+DELETE request
+--------------
+
+.. code-block:: php
+
+    <?php
+
+    $client = $this->clientService->newClient();
+    $response = $client->delete('https://api.domain.tld/pizza/42');
+
+OPTIONS request
+---------------
+
+.. code-block:: php
+
+    <?php
+
+    $client = $this->clientService->newClient();
+    $response = $client->options('https://nextcloud.com');
+    $status = $response->getStatusCode();
+    $allHeaders = $response->getHeaders();
+    $contentType = $response->getHeader('content-type');
+
+Error handling
+--------------
+
+Errors are signaled with exceptions. Catch PHP's base ``Exception``.
+
+.. code-block:: php
+
+    <?php
+
+    use Exception;
+
+    $client = $this->clientService->newClient();
+    try {
+        $response = $client->options('https://nextcloud.com');
+    } catch (Exception $e) {
+        // Handle the error
+    }

developer_manual/digging_deeper/index.rst

@@ -11,6 +11,7 @@ Digging deeper
    classloader
    continuous_integration
    flow
+   http_client
    javascript-apis
    npm
    notifications