2. HTTP Protocol Foundations

2.1 HTTP Evolution Overview

Hypertext Transfer Protocol (HTTP) has evolved through several versions, each addressing performance and scalability limitations, but maintaining the same fundamental client-server, request-response model.

HTTP Version	Key Characteristics	Relevance to Mobius HTTP Gateway
HTTP/1.1 (1997)	Text-based messages, no multiplexing, connection re-use via keep-alive. Stateless.	Primary basis for Mobius HTTP Gateway (Servlet-based model). Stateless request processing.
HTTP/2 (2015)	Binary framing, stream multiplexing, header compression (HPACK), but still TCP-based.	Compatible at transport level; Mobius can operate over HTTP/2/TLS channels without changing core architecture.
HTTP/3 (2022)	Runs over QUIC (UDP), independent stream control, better latency.	Future potential: Mobius Gateway's stateless, asynchronous design would also suit HTTP/3 transports when supported.

Mobius HTTP Gateway’s architecture aligns with the core semantics of HTTP across versions:

• Statelessness
• Client-initiated requests
• Resource-centric addressing (via URIs)

The evolution of HTTP improves transport efficiency, but does not change the core operational principles upon which Mobius HTTP Gateway relies.

2.2 Statelessness in HTTP

HTTP is designed as a stateless protocol, meaning:

• Each HTTP request must carry all necessary information for processing (headers, body, authentication).
• No memory of previous requests is assumed by the server.

In Mobius HTTP Gateway:

• Every incoming HTTP request is handled independently.
• WrappedServlet dynamically routes requests without session dependency.
• Any application-level state (e.g., user sessions, transaction state) must be handled externally, via higher-layer mechanisms like tokens or client-managed context.

2.3 Client-Server Model and Resource-Based Interaction

In HTTP:

• Clients initiate connections and send requests.
• Servers listen and respond.

HTTP requests target resources via URIs. Each concrete HTTP connection could be defined: either inbound (acting as a server) or outbound (acting as a client).
In Mobius HTTP Gateway:

HTTP Concept	Mobius Component
Resource Identification (URI)	HttpLink.url defines the inbound matching path.
Server Binding	HttpServer binds a serviceName to Links at a Destination.
Business Logic Execution	HttpCallbackInterface processes matched requests.

Mobius Gateway preserves HTTP's client-server semantics, while dynamically managing service registrations at runtime.

2.4 Transport Protocol Dependency and Stack Operation

HTTP requires a reliable, ordered transport layer.

Transport	Characteristics	Gateway Support
TCP (HTTP/1.1)	Reliable, ordered, stream-based transport.	Fully supported (primary transport).
TLS/TCP (HTTPS)	Secure transport via TLS encryption.	Supported via configured TLS certificates in HttpConfiguration and HttpLink.
QUIC/UDP (HTTP/3)	Reliable over UDP with multiplexing.	Not directly supported yet (Servlet model relies on TCP).

In Mobius HTTP Gateway:

• Each HttpServerData instance owns an Undertow server listening on a configured local TCP port.
• These Undertow servers are started and stopped programmatically by the Mobius stack (inside classes like HttpStandaloneServer and HttpStarter).
• Undertow runs a single servlet: the WrappedServlet — which handles all incoming HTTP requests for that port.

Mobius HTTP Gateway is transport-agnostic at application layer — as long as a reliable TCP-based HTTP connection is available, it can route and process requests without modification.

2.5 Payload Formats and Content-Type Handling

Modern APIs, including telecom systems, use structured, typed payloads over HTTP.

Content-Type	Description	Mobius Support
application/json	JSON payloads for request/response bodies (dominant for REST APIs).	Fully supported with dynamic deserialization/serialization via Jackson.
application/xml	XML payloads, often used in legacy or telecom-specific APIs.	Supported, including XML root wrapping/unwrapping (xmlRootName).
application/x-www-form-urlencoded	Form-encoded payloads for lightweight data transmission (e.g., OAuth).	Supported and automatically parsed.

Mobius processing flow:

• Incoming Content-Type is detected.
• Request body is parsed to a Java object of the expected class.
• Response is serialized according to the response MediaType indicated.

Note: Developers can specify expected content types dynamically via AtomicReference<MediaType> inside the onMessage() processing.

2.6 Protocol Parameters and Messaging

HTTP Request Structure
A client sends an HTTP request to a server in the form of a request message, beginning with a request-line that includes a method, URI, and protocol version, followed by header fields containing request modifiers, client information, and representation metadata, an empty line to indicate the end of the header section, and finally a message body containing the payload body (if any). (Section 3, [RFC7230])​.
A request-line begins with a method token, followed by a single space (SP), the request-target, another single space (SP), the protocol version, and ends with CRLF. The method token indicates the request method to be performed on the target resource. The request method is case-sensitive.
A client must send a Host header field in an HTTP/1.1 request even if the request-target is in the absolute-form (full URL of the resource being requested, including the scheme, the hostname, and the path.), since this allows the Host information to be forwarded through ancient HTTP/1.0 proxies that might not have implemented Host. HTTP/1.1 requires Host in every request, or else the server must reject the message with “400 Bad Request” (Section 5.4, [RFC7230])​.

Example: For a simple GET request, the message might look like:
GET /hello.txt HTTP/1.1
Host: www.example.com
User-Agent: curl/7.16.3 libcurl/7.16.3
Accept-Language: en, mi
(This includes a request line with method GET, path /hello.txt, version HTTP/1.1, followed by required Host header and other request headers.)​

HTTP Response Structure
A server responds to a client’s request by sending one or more HTTP response messages, each beginning with a status line that includes the protocol version, a success or error code, and textual reason phrase, possibly followed by header fields containing server information, resource metadata, and representation metadata, an empty line to indicate the end of the header section, and finally a message body containing the payload body (if any), (Section 3, [RFC7230]).
The first line of a response message is the status-line, consisting of the protocol version, a space (SP), the status code, another space, a possibly empty textual phrase describing the status code, and ending with CRLF. The status-code element is a 3-digit integer code describing the result of the server's attempt to understand and satisfy the client's corresponding request.
Example: A 200 OK response message could look like:

HTTP/1.1 200 OK  
Date: Mon, 27 Jul 2009 12:28:53 GMT  
Server: Apache  
Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT  
ETag: "34aa387-d-1568eb00"  
Accept-Ranges: bytes  
Content-Length: 51  
Content-Type: text/plain

Hello World! My payload includes a trailing CRLF.

(Status line with version HTTP/1.1, code 200, reason OK; headers like Date, Server, resource metadata (Last-Modified, ETag), representation metadata (Content-Length, Content-Type), a blank line, and then the message body).

Header Fields
General Header Fields (Control Data): HTTP header fields are case-insensitive name/value pairs that can appear in requests or responses. The order in which header fields with differing field names are received is not significant. However, it is good practice to send header fields that contain control data first, such as Host on requests and Date on responses, so that implementations can decide when not to handle a message as early as possible. (Section 3.2.2, [RFC7230])​.

Request Header Fields: These are sent by the client to provide context or constraints on the request. A client sends request header fields to provide more information about the request context, make the request conditional based on the target resource state, suggest preferred formats for the response, supply authentication credentials, or modify the expected request processing. These fields act as request modifiers, similar to the parameters on a programming language method invocation [RFC7231]​.

Response Header Fields: These are sent by the server to add additional information about the response. The response header fields allow the server to pass additional information about the response beyond what is placed in the status-line. These header fields give information about the server, about further access to the target resource, or about related resources. Although each response header field has a defined meaning, in general, the precise semantics might be further refined by the semantics of the request method and/or response status code [RFC7231]​.

Entity/Representation Header Fields: These headers describe the body of the message (the representation of the resource). When a message includes a payload body, the representation header fields describe how to interpret the representation data enclosed in the payload body. In a response to a HEAD request, the representation header fields describe the representation data that would have been enclosed in the payload body if the same request had been a GET. For example, Content-Type, Content-Language, Content-Encoding, and Content-Location are representation metadata header fields that define the nature of the payload content [RFC7231]​.

Status Codes
The first digit of the status-code defines the class of response. The last two digits do not have any categorization role. There are five values for the first digit:
1xx (Informational): The request was received, continuing process
2xx (Successful): The request was successfully received, understood, and accepted
3xx (Redirection): Further action needs to be taken in order to complete the request
4xx (Client Error): The request contains bad syntax or cannot be fulfilled
5xx (Server Error): The server failed to fulfill an apparently valid request.
(Section 6, [RFC7231])​
Note: Besides the standard codes, the HTTP/1.1 specification defines many other codes (e.g. 301 Moved Permanently, 302 Found, 307 Temporary Redirect for redirections, 410 Gone, etc.), and additional codes have been introduced in later RFCs (such as 308 Permanent Redirect in [RFC7538]).

Problem Details for APIs 
Error responses (4xx and 5xx) are often returned with a structured JSON body providing details about the problem. The IETF defines a standard format for this in [RFC7807], and [TS 29.500] mandates its use for SBA. In 5G SBA the 3GPP NF shall also support the handling of the ‘ProblemDetails’ JSON object with the Content-Type header field set to ‘application/problem+json’ for HTTP status codes 4xx and 5xx, when no other body is specified​. The ProblemDetails object includes standard fields like type, title, status, detail, instance, and may be extended with application-specific fields. In 3GPP APIs, ProblemDetails is extended with: a “cause” string for a machine-readable error code, and an array of “invalidParams” (objects with a parameter name and a reason description) to detail input errors.
For example, an HTTP response with a Problem Details body might be:
HTTP/1.1 403 Forbidden  
Content-Type: application/problem+json  
Content-Language: en

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/msgs/abc",
  "balance": 30,
  "accounts": [ "/account/12345", "/account/67890" ]
}

Here, the 403 Forbidden status code is accompanied by a JSON object providing a human-readable error summary (title), a specific error description (detail), a URI identifying the error type, an instance URI to correlate to the exact occurrence, and two extension fields: balance (application-specific info) and accounts (related resources)​.

2.7. HTTP Methods

Safe and Idempotent Methods

HTTP defines safe methods as those intended for read-only operations that do not request any state change on the server. In other words, using a safe method should not have side effects that the client is accountable for. For example, a safe request might trigger server-side logging or advertising impressions, but those happen without the client’s intent to modify state. According to Section 4.2.1 [RFC7231], the methods GET, HEAD, OPTIONS, and TRACE are defined to be safe. Safe methods are important for tasks like web crawling or pre-fetching, where automated agents can perform them without risking unintended changes on the server.

An idempotent method is one that can be called many times without different outcomes. Section 4.2.2 [RFC7231] states that a method is idempotent if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request. All safe methods are idempotent, since doing nothing twice is the same as doing it once. In addition, PUT and DELETE are defined as idempotent in HTTP. This means, for example, deleting a resource twice has the same result as deleting it once (the resource is gone) and PUTting the same representation multiple times yields no further change after the first. In contrast, POST is not idempotent or safe​ – multiple identical POSTs usually result in multiple subordinate resources or repeated side effects. Clients, especially intermediaries, should take care to avoid unintended repeats of unsafe, non-idempotent requests (e.g., by retrying a purchase operation) because they can cause unintended effects on the server.

Resource-Modifying Methods

Methods like POST, PUT, PATCH, and DELETE are used to modify resources on the server. They are not safe (they do request state changes) and except for PUT and DELETE, not idempotent. Each has distinct semantics regarding what part of a resource’s state they affect and what payload is expected.
POST – Process subordinate or annotated data. The POST method is quite general; it asks the target resource to perform resource-specific processing on the request payload. This often results in a new resource being created subordinate to the target (for example, posting to /items/ to create a new item) or it may trigger a server-side process using the data. Because the outcome of a POST is defined by the server and can vary with each request, POST is neither safe nor idempotent​. Section 4.3.3 [RFC7231] notes that if a POST results in a new resource, the server should send a 201 (Created) status and a Location header with the URI of the new resource; otherwise a 200 (OK) or other appropriate status is used, based on the server’s processing result (e.g., returning a 200 OK with a representation of an action’s result).

PUT – Replace a resource entirely. The PUT method requests that the payload be stored as the new entire representation of the target resource. In other words, PUT completely replaces the state of a resource with the request body. If the target resource doesn’t exist, PUT can create it (the client is specifying the new resource’s URI by PUTting to it). Importantly, PUT is defined to be idempotent – sending the same PUT again results in the same state as after the first request. Servers should treat a PUT as a full update: for example, if fields are omitted in the PUT payload, the server may delete those omitted fields, interpreting absence as intentional removal (since the client is overwriting the resource with the provided representation). For a successful PUT that creates a new resource, a 201 (Created) response is appropriate; if it instead replaced an existing resource, the server can respond 200 (OK) (often with the updated representation) or 204 (No Content) if no body is returned. Section 4.3.4 [RFC7231].

PATCH – Modify part of a resource. Unlike PUT, PATCH does not send a whole new resource representation, but rather a description of changes to apply. As [RFC5789] explains, with PUT the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced, whereas with PATCH, however, the enclosed entity contains a set of instructions describing how to modify [the resource] to produce a new version. For example, a PATCH payload might instruct the server to change the value of field X to 7 or remove element Y from an array. The format of these patch instructions is not fixed by the HTTP spec – it could be a diff, a JSON Patch, an XML patch document, etc., as indicated by the Content-Type. Because PATCH applies a delta, it’s inherently not idempotent by default (applying the same patch twice could double-apply a change). However, [RFC5789] notes it can be made idempotent by the client if needed (for example, by using conditional requests with ETags to ensure the patch only applies once). In practice, servers often treat PATCH as “partial update” and may return 200 (OK) with the updated resource or 204 (No Content) if the update is successful with no response body. A server advertises support for PATCH by including an Accept-Patch header in responses to OPTIONS requests.

DELETE – Remove a resource. The DELETE method requests that the origin server remove the target resource – for example, delete a file or record identified by the URI. DELETE is idempotent: after a resource is deleted, repeating the same DELETE on that resource should result in the same state (the resource remains nonexistent) even if the response might differ (first deletion might return success, subsequent ones might be 404 Not Found). Section 4.3.5 [RFC7231] suggests that a server respond with 202 (Accepted) if a delete request is accepted but not yet fully carried out (e.g. deletion is queued), 204 (No Content) if the deletion has been enacted and there’s nothing more to return, or 200 (OK) if the server has performed the deletion and is returning a status representation. In other words, a successful DELETE often yields no content; the operation “does not have a response body” in many cases. (If the server wants to convey additional info about the deletion, it can use 200 and include that in the body).

All of these methods can change server state, so they are not safe. Clients should use them with intent to modify something. Additionally, servers can restrict which resource-modifying methods are allowed on a given resource. For example, some resources might support only GET and not allow PUT or DELETE. If a method is not allowed on a resource that does recognize it, the server should return 405 (Method Not Allowed) and include an Allow header listing the allowed methods. If the server doesn’t recognize or implement the method at all, it should return 501 (Not Implemented).
The distinction between complete replacement and partial update is a key design consideration for APIs. Use PUT when the client can send the full new state of the resource, and use PATCH when it’s preferable to send only the changes. As noted in [RFC5789], PUT is idempotent and has broad support, whereas PATCH is more flexible for complex or bandwidth-sensitive updates but requires the server to understand the patch format and is not automatically idempotent.