doc: Add HTTP client migration notes for NCS Serial LTE Modem

Document the changes required to migrate from the NCS SLM HTTP client
API to the new HTTP client API in the Serial Modem add-on.

Rename the <socket_fd> parameter to <handle> for consistency with the
AT socket documentation.

Jira: SM-298

Signed-off-by: Juha Ylinen <juha.ylinen@nordicsemi.no>

Author: juhaylinen

app/src/sm_at_httpc.c

@@ -584,7 +584,7 @@ static bool http_headers_complete(struct http_request *req, char *header_end,
 		/*
 		 * Keep piggybacked body bytes (if any) for the first pull.
 		 * Stop XAPOLL so only the host drives reception via
-		 * AT#XHTTPCDATA=<socket_fd>.
+		 * AT#XHTTPCDATA=<handle>.
 		 */
 		if (body_len > 0)
 			memmove(req->recv_buf, req->recv_buf + body_offset, body_len);
@@ -992,7 +992,7 @@ STATIC int handle_at_httpcreq(enum at_parser_cmd_type cmd_type, struct at_parser
 		/* Validate socket exists */
 		sock = find_socket(socket_fd);
 		if (!sock) {
-			LOG_ERR("Invalid socket FD: %d", socket_fd);
+			LOG_ERR("Invalid socket fd: %d", socket_fd);
 			return -EINVAL;
 		}
 
@@ -1191,7 +1191,7 @@ STATIC int handle_at_httpcreq(enum at_parser_cmd_type cmd_type, struct at_parser
 	}
 
 	case AT_PARSER_CMD_TYPE_TEST:
-		rsp_send("\r\n#XHTTPCREQ: <socket_fd>,<url>,<method>"
+		rsp_send("\r\n#XHTTPCREQ: <handle>,<url>,<method>"
 			 "[,<auto_reception>[,<body_len>[,<header>]...]]\r\n");
 
 		err = 0;
@@ -1325,7 +1325,7 @@ STATIC int handle_at_httpcdata(enum at_parser_cmd_type cmd_type, struct at_parse
 	}
 
 	case AT_PARSER_CMD_TYPE_TEST:
-		rsp_send("\r\n#XHTTPCDATA: <socket_fd>[,<length>]\r\n");
+		rsp_send("\r\n#XHTTPCDATA: <handle>[,<length>]\r\n");
 
 		err = 0;
 		break;
@@ -1371,7 +1371,7 @@ STATIC int handle_at_httpccancel(enum at_parser_cmd_type cmd_type, struct at_par
 		break;
 
 	case AT_PARSER_CMD_TYPE_TEST:
-		rsp_send("\r\n#XHTTPCCANCEL: <socket_fd>\r\n");
+		rsp_send("\r\n#XHTTPCCANCEL: <handle>\r\n");
 		break;
 
 	default:

doc/app/at_httpc.rst

@@ -35,10 +35,10 @@ Syntax
 
 ::
 
-   AT#XHTTPCREQ=<socket_fd>,<url>,<method>[,<auto_reception>[,<body_len>[,<header 1>[,<header 2>[...]]]]]
+   AT#XHTTPCREQ=<handle>,<url>,<method>[,<auto_reception>[,<body_len>[,<header 1>[,<header 2>[...]]]]]
 
-* The ``<socket_fd>`` parameter is an integer.
-  It identifies the connected socket file descriptor returned by ``AT#XSOCKET`` or ``AT#XSSOCKET``.
+* The ``<handle>`` parameter is an integer.
+  It identifies the connected socket handle returned by ``AT#XSOCKET`` or ``AT#XSSOCKET``, and connected by ``AT#XCONNECT``.
 
 * The ``<url>`` parameter is a string.
   It specifies the full URL of the request, for example, ``http://host/path`` or ``https://host/path``.
@@ -91,20 +91,20 @@ Response syntax
 
 ::
 
-   #XHTTPCREQ: <socket_fd>
+   #XHTTPCREQ: <handle>
    OK
 
-* The ``<socket_fd>`` parameter is an integer.
+* The ``<handle>`` parameter is an integer.
   It identifies the socket.
 
 Unsolicited notification
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``#XHTTPCHEAD`` is emitted when response headers have been parsed::
 
-   #XHTTPCHEAD: <socket_fd>,<status_code>,<content_length>
+   #XHTTPCHEAD: <handle>,<status_code>,<content_length>
 
-* The ``<socket_fd>`` parameter is an integer.
+* The ``<handle>`` parameter is an integer.
   It identifies the socket.
 * The ``<status_code>`` parameter is an integer.
   It contains the HTTP status code returned by the server.
@@ -113,11 +113,11 @@ Unsolicited notification
 
 ``#XHTTPCDATA`` is emitted in automatic mode for each received body chunk::
 
-   #XHTTPCDATA: <socket_fd>,<offset>,<length>
+   #XHTTPCDATA: <handle>,<offset>,<length>
 
 The notification line is terminated with ``\r\n`` and the raw body bytes follow immediately with no additional separator.
 
-* The ``<socket_fd>`` parameter is an integer.
+* The ``<handle>`` parameter is an integer.
   It identifies the socket.
 * The ``<offset>`` parameter is an integer.
   It contains the number of body bytes already delivered before this chunk.
@@ -126,9 +126,9 @@ The notification line is terminated with ``\r\n`` and the raw body bytes follow
 
 ``#XHTTPCSTAT`` is emitted when the request completes, fails, or is cancelled::
 
-   #XHTTPCSTAT: <socket_fd>,<status_code>,<total_bytes>
+   #XHTTPCSTAT: <handle>,<status_code>,<total_bytes>
 
-* The ``<socket_fd>`` parameter is an integer.
+* The ``<handle>`` parameter is an integer.
   It identifies the socket.
 * The ``<status_code>`` parameter is an integer.
   It contains the HTTP status code on success, or ``-1`` on failure, cancel, or timeout.
@@ -252,15 +252,15 @@ Response syntax
 
 ::
 
-   #XHTTPCREQ: <socket_fd>,<url>,<method>[,<auto_reception>[,<body_len>[,<header>]...]]
+   #XHTTPCREQ: <handle>,<url>,<method>[,<auto_reception>[,<body_len>[,<header>]...]]
 
 Example
 ~~~~~~~
 
 ::
 
    AT#XHTTPCREQ=?
-   #XHTTPCREQ: <socket_fd>,<url>,<method>[,<auto_reception>[,<body_len>[,<header>]...]]
+   #XHTTPCREQ: <handle>,<url>,<method>[,<auto_reception>[,<body_len>[,<header>]...]]
    OK
 
 HTTP data pull #XHTTPCDATA
@@ -278,9 +278,9 @@ Syntax
 
 ::
 
-   AT#XHTTPCDATA=<socket_fd>[,<length>]
+   AT#XHTTPCDATA=<handle>[,<length>]
 
-* The ``<socket_fd>`` parameter is an integer.
+* The ``<handle>`` parameter is an integer.
   It identifies the socket used when starting the manual-mode request.
 
 * The ``<length>`` parameter is an optional integer.
@@ -292,7 +292,7 @@ Response syntax
 
 When body data is available::
 
-   #XHTTPCDATA: <socket_fd>,<offset>,<length>
+   #XHTTPCDATA: <handle>,<offset>,<length>
    <length bytes of raw body data>
    OK
 
@@ -302,10 +302,10 @@ The ``#XHTTPCDATA:`` line is terminated with ``\r\n``.
 
 When the socket buffer is temporarily empty (EAGAIN)::
 
-   #XHTTPCDATA: <socket_fd>,<offset>,0
+   #XHTTPCDATA: <handle>,<offset>,0
    OK
 
-* The ``<socket_fd>`` parameter is an integer.
+* The ``<handle>`` parameter is an integer.
   It identifies the socket.
 * The ``<offset>`` parameter is an integer.
   It contains the number of body bytes already delivered before this pull.
@@ -319,8 +319,8 @@ when the ``Content-Length`` bytes have all been forwarded.
 
 .. note::
 
-   Retry the pull after a brief delay when ``#XHTTPCDATA: <socket_fd>,<offset>,0`` is received.
-   Use ``AT#XHTTPCCANCEL=<socket_fd>`` to cancel if no more data is needed.
+   Retry the pull after a brief delay when ``#XHTTPCDATA: <handle>,<offset>,0`` is received.
+   Use ``AT#XHTTPCCANCEL=<handle>`` to cancel if no more data is needed.
 
 Example
 ~~~~~~~
@@ -356,15 +356,15 @@ Response syntax
 
 ::
 
-   #XHTTPCDATA: <socket_fd>[,<length>]
+   #XHTTPCDATA: <handle>[,<length>]
 
 Example
 ~~~~~~~
 
 ::
 
    AT#XHTTPCDATA=?
-   #XHTTPCDATA: <socket_fd>[,<length>]
+   #XHTTPCDATA: <handle>[,<length>]
    OK
 
 Idle timeout
@@ -377,7 +377,7 @@ The timer resets each time data is sent or received:
 * Receiving response headers or body bytes.
 * Pulling a body chunk in manual mode (``AT#XHTTPCDATA``).
 
-If no such activity occurs within the configured window, the request is aborted and ``#XHTTPCSTAT: <socket_fd>,-1,<total_bytes>`` is emitted.
+If no such activity occurs within the configured window, the request is aborted and ``#XHTTPCSTAT: <handle>,-1,<total_bytes>`` is emitted.
 The timeout is enforced by a background timer that fires independently of normal socket poll events, so a server that stalls silently (no TCP RST or FIN) is also detected.
 
 HTTP request cancel #XHTTPCCANCEL
@@ -395,12 +395,12 @@ Syntax
 
 ::
 
-   AT#XHTTPCCANCEL=<socket_fd>
+   AT#XHTTPCCANCEL=<handle>
 
-* The ``<socket_fd>`` parameter is an integer.
+* The ``<handle>`` parameter is an integer.
   It identifies the socket of the request to cancel.
 
-An unsolicited ``#XHTTPCSTAT: <socket_fd>,-1,<total_bytes>`` notification is emitted after cancellation, where ``<total_bytes>`` is the number of response body bytes already delivered to the host.
+An unsolicited ``#XHTTPCSTAT: <handle>,-1,<total_bytes>`` notification is emitted after cancellation, where ``<total_bytes>`` is the number of response body bytes already delivered to the host.
 
 Example
 ~~~~~~~
@@ -428,13 +428,13 @@ Response syntax
 
 ::
 
-   #XHTTPCCANCEL: <socket_fd>
+   #XHTTPCCANCEL: <handle>
 
 Example
 ~~~~~~~
 
 ::
 
    AT#XHTTPCCANCEL=?
-   #XHTTPCCANCEL: <socket_fd>
+   #XHTTPCCANCEL: <handle>
    OK

doc/releases/migration_notes_ncs_slm_v3.1.x.rst

@@ -231,6 +231,99 @@ Migration example:
         AT#XRECV=2,0,0,10         // Receive data from socket handle 2 with mode 0, no flags, 10s timeout
         AT#XCLOSE=1               // Close socket handle 1
 
+HTTP client changes
+-------------------
+
+The HTTP client has been redesigned from a dedicated connection-oriented interface to a socket-based interface.
+The old |NCS| SLM HTTP client kept its own HTTP connection state with ``AT#XHTTPCCON``, sent requests with ``AT#XHTTPCREQ``, and delivered the raw HTTP response stream followed by ``#XHTTPCRSP`` notifications.
+In |SM|, the HTTP client reuses Socket AT commands for transport setup and provides dedicated HTTP AT commands for requests and notifications, including headers, body data, and completion status.
+
+The following is the list of changes:
+
+* Removed ``AT#XHTTPCCON``.
+
+  * Create a plain TCP socket with ``AT#XSOCKET`` or a TLS socket with ``AT#XSSOCKET``.
+  * Configure TLS options such as security tag and peer verification with ``AT#XSSOCKETOPT``.
+  * Establish the transport connection with ``AT#XCONNECT=<handle>,<host>,<port>``.
+  * Close the connection with ``AT#XCLOSE`` when no more requests are needed.
+
+* Updated ``AT#XHTTPCREQ`` to operate on an already connected socket.
+
+  * Old syntax: ``AT#XHTTPCREQ=<method>,<resource>[,<headers>[,<content_type>,<content_length>[,<chunked_transfer>]]]``
+  * New syntax: ``AT#XHTTPCREQ=<handle>,<url>,<method>[,<auto_reception>[,<body_len>[,<header 1>[,<header 2>[...]]]]]``
+
+* Changed request parameter model.
+
+  * ``<method>`` changed from a string such as ``"GET"`` or ``"POST"`` to an integer:
+
+    * ``0`` - GET
+    * ``1`` - POST
+    * ``2`` - PUT
+    * ``3`` - DELETE
+    * ``4`` - HEAD
+
+  * ``<resource>`` is replaced by a full ``<url>`` parameter.
+  * Optional headers are no longer passed as one CRLF-delimited string.
+    Each header is now passed as a separate optional parameter.
+  * For POST and PUT, the body upload length is given with ``<body_len>``.
+    The command then enters data mode and the host must send exactly that many bytes.
+  * For GET or HEAD requests with extra headers, set ``<body_len>`` to ``0`` as a placeholder before the header parameters.
+
+* Changed response delivery model.
+
+  * Removed the old raw response plus ``#XHTTPCRSP: <received_byte_count>,<state>`` framing.
+  * Response headers are now reported with ``#XHTTPCHEAD: <handle>,<status_code>,<content_length>``.
+  * In automatic mode, response body chunks are reported with ``#XHTTPCDATA: <handle>,<offset>,<length>`` and the raw body bytes follow immediately.
+  * In manual mode, the host pulls body chunks explicitly with ``AT#XHTTPCDATA=<handle>[,<length>]``.
+  * Request completion including failure, timeout, or cancel is reported with ``#XHTTPCSTAT: <handle>,<status_code>,<total_bytes>``.
+
+* Added request cancellation with ``AT#XHTTPCCANCEL=<handle>``.
+
+Migration example:
+
+     Old approach (|NCS| SLM):
+
+     .. code-block::
+
+        AT#XHTTPCCON=1,"postman-echo.com",80
+        #XHTTPCCON: 1
+        OK
+
+        AT#XHTTPCREQ="GET","/get?foo1=bar1&foo2=bar2"
+        OK
+        #XHTTPCREQ: 0
+
+        HTTP/1.1 200 OK
+        <headers>
+
+        #XHTTPCRSP: 244,1
+        <244 bytes of body>
+
+     New approach (|SM|):
+
+     .. code-block::
+
+        AT#XSOCKET=1,1,0
+        #XSOCKET: 0,1,6
+        OK
+
+        AT#XCONNECT=0,"postman-echo.com",80
+        #XCONNECT: 0,1
+        OK
+
+        AT#XHTTPCREQ=0,"http://postman-echo.com/get?foo1=bar1&foo2=bar2",0
+        #XHTTPCREQ: 0
+        OK
+
+        #XHTTPCHEAD: 0,200,244
+
+        #XHTTPCDATA: 0,0,244
+        <244 bytes of body>
+
+        #XHTTPCSTAT: 0,200,244
+
+For full details of the new interface, see :ref:`SM_AT_HTTPC` and :ref:`SM_AT_SOCKET`.
+
 PPP connection management changes
 ---------------------------------
 
@@ -589,7 +682,6 @@ If you need any of those features with this |SM|, please contact customer suppor
 
          OK
 
-  * HTTP client functionality, including ``AT#XHTTPCCON`` and ``AT#XHTTPCREQ`` commands, and ``#XHTTPCRSP`` notification.
   * FTP and TFTP clients, including ``AT#XFTP`` and ``AT#XTFTP`` commands.
   * The ``AT#XGPIO`` AT command.
   * The ``AT#XPOLL`` command.