From network communication to request processing in an API Gateway
In-depth edition - study and professional reference material
By João Ricardo Dutra••Complete material
Chapter Presentation
Corporate APIs appear, at first glance, as a technology concentrated in the application layer: a consumer sends a request, a service executes an operation and returns a response. However, this view hides an extensive chain of mechanisms. Before an method reaches the , the host name needs to be resolved, packets need to be routed, a connection must be established, cryptographic parameters need to be negotiated, and security policies can be evaluated at different components of the infrastructure.
This chapter presents this chain progressively. The goal is not to immediately transform the reader into an expert in networks but to provide a sufficiently precise mental model for understanding where a call may fail, which component has each responsibility, and why technologies such as , OAuth, JWT, , and Gateways depend on prior foundations. In subsequent chapters, each of these areas will be explored in depth.
The approach combines historical context, protocol theory, and practical application in corporate environments. Whenever possible, the text relates concepts to platforms like Axway and Azure Management. Examples use a fictitious banking client to demonstrate the complete communication path without exposing details of real-world environments.
How to Study This Chapter
Read the sections sequentially in your first pass. Then, read again following the end-to-end diagram and try to classify each possible failure by layer where it occurs. This practice prepares troubleshooting reasoning used by gateway teams and integration teams.
Learning Objectives
Distinguish between Internet, Web, , , and , avoiding the use of these terms as synonyms.
Explain how technical standards are defined by organizations such as the IETF, Editor, NIST,
IEEE, W3C, OpenID Foundation, and OpenAPI Initiative.
Understand , addressing, routing, ports, connections, name resolution,
and cryptographic protection at a conceptual level.
Describe the complete path of an HTTPS request from the consumer to a
protected by an .
Identify the typical responsibilities of firewalls, load balancers, proxies, gateways, identity
providers, and services.
Use the layered model to organize investigations of , , , and errors,
authentication, routing, and application errors.
Chapter Structure
1.1 Why Network Foundations Matter for APIs
1.2 Internet, Web and : Different Concepts
1.3 Historical Evolution of the Internet to Platform APIs
1.4 Ecosystem of Standardization
1.5 RFCs: How Protocols Are Documented
1.6 Network Communication and
1.7 OSI Model and / Model
1.8 Addressing and Routing
1.9 Resolution and Name Resolution
1.10 , UDP, Ports and Sockets
1.11 NAT, Firewall, Proxy and Load Balancing
1.12 , HTTPS and Trust
1.13 Anatomy of an Message
1.14 and the Concept of Resource
1.15 and Platform
1.16 End-to-End Journey
1.17 Layered Troubleshooting
1.18 Application in Corporate and Banking Environments
Summary, Exercises, Glossary and References
1.1 Why Network Foundations Matter for APIs
A team of Gateways works at the intersection between development, infrastructure, identity, and security. The gateway receives application messages but availability of this entry point depends on elements that exist before the application: , routes, addresses, ports, connections, and certificates. That's why an observed error such as 'the is not responding' can have causes completely different, from a name that does not resolve to a policy rejecting a token.
The same response may hide distinct origins. A 502 code could indicate the gateway failed to establish communication with the ; a 401 typically relates to authentication but can be produced by the gateway, identity provider, or service; a timeout can occur at the consumer, load balancer, gateway, or . Without a layered view, diagnosis tends to turn into trial and error.
Fundamental knowledge also improves architectural decisions. By understanding where confidentiality is guaranteed, the architect can differentiate transport security from message integrity. By understanding connections and sessions, they can evaluate effects of keep-alive, pooling, and termination. By understanding resolution, they can design failover, multiple environments, and service discovery strategies with fewer incorrect assumptions.
In this material, the term 'fundamentals' does not mean superficial content. It means studying the mechanisms that support more visible technologies such as OAuth 2.0, JWT, OpenID Connect, , and gateway policies. These concepts will be easier to understand when it is clear what happens before, during, and after a request transmission.
On the job
When a consumer reports a timeout, the initial question should not just be 'which gateway policy failed?'. First, determine if resolution, establishment, negotiation, and the request reaching the gateway listener occurred. Only then proceed to , authentication, and routing.
1.2 Internet, Web and : Different Concepts
Internet
The Internet is a global infrastructure formed by interconnecting independent networks. Each organization can operate its own links, routers, autonomous systems, and policies, but communication is possible because participants adopt common protocols. The term 'internet' in the generic sense means a network of networks; 'Internet', with an uppercase initial, usually refers to the public global system that uses the family of protocols.
The functioning of the Internet is decentralized. There is no single central server directing all messages. Telecommunications operators, cloud providers, companies, universities, and governments manage parts of the infrastructure. Routing between these parts allows packets to traverse multiple networks until reaching their destination. This characteristic explains why latency, packet loss, and asymmetric paths can vary even when the client and server do not change.
World Wide Web
The Web is a system of interconnected resources that uses the Internet as its infrastructure. It was conceived around resource identifiers, representations transferred between clients and servers, and links connecting documents. Popular browsers and web servers popularized , but the Internet existed before the Web and continues to transport many protocols not belonging to the Web.
Saying an is accessed via the Web generally means it uses technologies associated with the Web, especially , , and formats such as JSON. This does not transform every into a web page. The interface can be consumed by mobile apps, batch systems, devices, microservices, or partners without any browser interaction.
and RESTful
An is an interface created to allow one software to utilize the capabilities offered by another software. The interface defines operations, expected data, responses, errors, and usage rules. APIs exist at different levels: local libraries, operating systems, databases, messaging interfaces, and remote interfaces. Therefore, an is not synonymous with nor .
A RESTful is a remote interface designed according to the principles of the architectural style and typically exposed over . In market practice, many interfaces are called only because they use JSON and methods. A more rigorous evaluation also observes resource identification, method semantics, absence of session state on the server, caching, and layered architecture.
Essential distinction
The Internet is the infrastructure of networks. The Web is a system built upon this infrastructure. is an application protocol. An is a contract between software systems. is an architectural style. These concepts relate but are not equivalent.
1.3 Historical Evolution: From Packet Switching to Platforms
The earliest computer networks were often constructed for specific environments and had little interoperability. Research in packet switching introduced the idea of dividing data into smaller units that could traverse the network via shared paths. Instead of reserving a dedicated physical circuit throughout communication, the network could use its capacity statistically and reconstruct the data at the destination.
The ARPANET, operational since 1969, was one of the projects demonstrating the viability of this approach in long-distance networks. It was not the modern Internet but provided technical and organizational experience for subsequent evolution. The next challenge was not just to connect computers within a single network but to allow different networks to communicate without requiring a unique physical technology.
The / suite emerged to resolve this interconnection problem. The layer provides a mechanism for addressing and delivering datagrams between networks, while transport protocols such as provide additional properties to applications. The adoption of / by the ARPANET in 1983 is traditionally considered a milestone in consolidating the modern Internet.
By the late 1980s and early 1990s, the Web added a layer for resource publication and navigation. , , and HTML formed a simple, extensible, and distributed system.
With the growth of dynamic applications, began to transport not only documents for people but data between systems.
In the early 2000s, service-oriented architectures and web APIs gained importance in corporate integration. became popular for aligning with the already widespread infrastructure of the Web. Subsequently, cloud computing, microservices, mobile applications, and partner ecosystems increased the number of APIs and consumers, creating a need for governance, protection, and observability at scale.
It is within this context that modern management platforms emerged. An began to function as a controlled point of exposure and mediation, while management plane components handled configuration, cataloging, publication, analytics, and the lifecycle. Products such as Axway and Azure Management represent corporate implementations of this evolution.
Figure 1 - Simplified timeline of network infrastructure leading up to platforms.
Critical Reading
The evolution did not occur as a complete replacement. Old and new technologies coexist. /1.1 remains present alongside /2 and /3; 1.2 can still coexist with 1.3; legacy systems may be exposed by modern gateways. Corporate architecture requires understanding these combinations.
1.4 Standardization Ecosystem and Technical References
IETF and Editor
The Internet Engineering Task Force (IETF) is an open community responsible for developing many standards used in the Internet. Work is organized into groups that discuss technical problems, analyze proposals, and produce documents. Protocols such as , , , , OAuth 2.0, and various security mechanisms are defined or updated within this ecosystem.
The Editor publishes and maintains the series of RFCs. An receives a permanent number and is not edited after publication. When an specification needs to be corrected or replaced, a new is published and records its relationship with previous documents, for example "updates" or "obsoletes". This characteristic is important: when researching a protocol, professionals should verify if the found is still current.
NIST, W3C, IEEE and other organizations
The National Institute of Standards and Technology (NIST) publishes widely used standards in security, cryptography, identity, and risk management. Although an institution from the United States, its publications influence organizations across multiple countries. For APIs, documents from NIST help organize protection controls during development, deployment, and operation.
The World Wide Web Consortium (W3C) produces standards related to the web platform, including technologies used by browsers. The Institute of Electrical and Electronics Engineers (IEEE) maintains important standards at the physical and link layers, such as Ethernet and Wi-Fi families. These standards are below but directly affect connectivity, capacity, and network behavior.
The OpenID Foundation maintains specifications related to identity, including OpenID Connect and profiles used in financial ecosystems. The OpenAPI Initiative maintains the OpenAPI specification, which is used for describing contracts in a readable manner by both people and tools. OASIS maintains standards such as SAML. Each organization acts within its domain, and corporate projects frequently combine specifications from multiple sources.
How to evaluate the authority of a document
Manufacturer documentation explains how a product implements a standard but does not replace the normative specification. To understand Azure APIM behavior, consult Microsoft; for Axway , consult Axway. However, to understand semantics, consult the applicable . This distinction avoids conflating product decisions with protocol requirements.
An efficient study strategy comprises three levels. First, a didactic introduction establishes vocabulary. Second, the official specification clarifies normative requirements and edge cases. Finally, product documentation demonstrates how to configure or observe that behavior in an implementation-specific manner. This sequence reduces the risk of learning only procedures without understanding fundamentals.
Rule of thumb
To answer 'what does the protocol allow?', look at the specification. To answer 'how does the product implement or configure this?', look at manufacturer documentation. To answer 'which control is recommended?', consult security and risk guides such as NIST and OWASP.
1.5 RFCs: How Protocols Are Documented and Evolve
stands for Request for Comments, a historical name that has remained even when parts of the series began registering consolidated standards. Not all RFCs are Internet Standards. There exist documents in different tracks and categories, including Standards Track, Best Current Practice, Informational, and Experimental. Therefore, citing only a number without verifying its status can lead to incorrect conclusions.
Before publication, proposals from IETF typically circulate as Internet-Drafts. A draft is a temporary document: it may change, expire, or never become an . During analysis, participants discuss interoperability, security, clarity, and implementation experience. The goal is not merely to produce a polished description but to allow independent implementations to communicate correctly.
RFCs use normative words such as MUST, MUST NOT, SHOULD, and MAY according to specific conventions. In a technical reading, these words indicate different levels of obligation. MUST describes an essential requirement for conformity; SHOULD allows justified exceptions; MAY indicates permitted optionality. Informal translations may soften these differences and alter interpretation.
The evolution of highlights the importance of tracking document relationships. Older RFCs may remain heavily cited despite being superseded. Modern semantics are consolidated in 9110, while transport versions have their own documents. also received a more recent consolidation specification in 9293, which supersedes the historic 793.
When studying an , start with the summary, status, relationship to other documents, and abstract. Then identify terminology, operational model, normative requirements, and security section. You do not need to memorize the entire document. The initial goal is to learn how to locate the formal source of a query and interpret the relevant excerpt in the correct context.
Simplified regulatory vocabulary
MUST requirement mandatory
MUST NOT prohibited behavior
SHOULD recommended, unless justified by technical reasons
MAY optional per specification
Example investigation
When encountering a configuration that accepts 1.0, do not conclude based solely on the product's screen showing it as recommended. Verify the standard, current security guidelines, and organizational policy. Technical capability to configure does not equate to a secure decision.
1.6 Network Communication, Packets, and
Applications work with meaningful messages for business: a request to consult a client, a JSON response, or an access token. However, the network infrastructure must transport these data through means with size limits, address specifications, and own rules. Each layer adds control information to the content received from the upper layer. This process is called .
In an call over and , the application produces bytes of an message. organizes these bytes into protected records. treats the flow as a reliable sequence and creates segments. appends source and destination addresses to datagrams. The link technology creates appropriate frames for the local medium, such as Ethernet or Wi-Fi. At the destination, each layer removes and interprets its header before passing the content to the upper layer.
This separation allows independent evolution. The same application can operate over different physical networks, and the same link can transport different upper-layer protocols. This explains why diagnostic tools show distinct views: a packet capture might display addresses and ports, while gateway logs reveal methods, paths, and headers.
The size of data matters. Interfaces have a Maximum Transmission Unit (MTU), and larger messages need to be split or adjusted to fit the path's limits. MTU issues and fragmentation can produce hard-to-detect symptoms, such as connections working for small messages but failing with large certificates, extensive headers, or uploads.
does not mean that all layers are equally visible in each component. A router primarily routes based on information. A layer 4 load balancer may use and port information. A layer 7 proxy interprets . A gateway can inspect the method, , token, and body. The higher the operational layer, the greater the semantic understanding of the message, and typically the higher the processing cost.
Figure 2 - Simplified View of -Protected Call .
Relation to Observability
Application logs, gateway logs, distributed traces, and packet captures observe at different levels. A complete investigation may require correlating timestamps, address, port, SNI, method, correlation ID, and trace ID.
1.7 OSI Model and / Model
Layered models are conceptual tools. They help separate responsibilities and organize reasoning, but do not perfectly represent all details of an implementation. The OSI model describes seven layers: physical, link, network, transport, session, presentation, and application. The / model is often presented with four or five layers, grouping functions in a manner closer to the Internet architecture.
In practice, the most cited layers are network, transport, and application. belongs to the network layer; and UDP belong to the transport layer; , , and identity protocols appear at the application layer. is frequently positioned between application and transport, although its classification varies depending on the model used. The important thing is to understand its function rather than just disputing which layer number it occupies.
The OSI model is useful for troubleshooting because it encourages an order of operations. First, do we have physical or virtual connectivity? Next, can the address be reached? Does the transport port accept connections? Is negotiation complete? Is the message valid? Is authentication accepted? Does the business rule work? This path reduces investigations that start from complex policies when the problem is a missing route.
Terms like 'layer 4 balancer' and 'layer 7 proxy' derive from this vocabulary. A layer 4 device primarily makes decisions based on transport address and port information. A layer 7 component interprets the application protocol and can route by host, path, or header. An is typically a layer 7 component, although it depends on resources from lower layers.
Table 1 - Approximate Mapping between OSI and TCP/IP.
OSI
TCP/IP approximate
Examples in the context of APIs
Layer 7 Application
Application Layer
HTTP, DNS, OAuth, OpenID Connect
Layer 6 Presentation
Application Layer
JSON, encoding, serialization, TLS in some models
Layer 5 Session
Application Layer
Logical sessions, negotiation, and context
4 Transporte
Transporte
TCP, UDP, QUIC
3 Network
Internet
IPv4, IPv6, routing
2 Link
Network access
Ethernet, Wi-Fi, VLAN
1 Physical
Network access
Cable, fiber, radio
1.8 Addressing and Routing
The protocol provides logical addressing and datagram delivery between networks. An address identifies a network interface in a given context of the network, not necessarily a person, application or machine permanently. Devices may have multiple addresses, addresses can change, and intermediary mechanisms may translate sources and destinations.
IPv4 uses 32-bit addresses and is typically represented by four decimal numbers. IPv6 uses 128 bits and hexadecimal representation, offering much larger space and other architectural improvements. In corporate networks, private IPv4 continues to be common, while IPv6 can appear increasingly in external environments, cloud, and modern networks. An may publish records for both families.
A mask or prefix identifies which part of the address corresponds to the network. When the destination is outside the local network, the host sends the datagram to the default gateway. Routers consult their tables and forward the packet hop-by-hop. Each router decides the next path; it does not need to know logic, only enough information to reach the target network.
Routing differs from routing. The former occurs in infrastructure and chooses paths between networks. The latter happens at proxies and gateways and may choose a based on host, path, version, header or policy. An routing failure prevents connection before the gateway analyzes ; an routing failure occurs after the message has already reached the gateway.
In cloud and data centers, routes can be influenced by virtual networks, subnets, tunnels, security appliances, and output rules. Being in the same company does not guarantee direct connectivity. Architects should treat network path, resolution, firewall rules, and output dependencies as explicit parts of the design.
Conceptual example of addressing
Example private IPv4: 10.20.30.40/24
Approximate network: 10.20.30.0/24
Default gateway: 10.20.30.1
External destination: forwarded to the gateway
Diagnosis
If the name resolves but the connection times out without a response, investigate path, firewall, routing, and listener. If the connection is immediately refused, the target may be reachable but with no service listening on that port or due to active rejection.
1.9 Resolution and Name Resolution
The Domain Name System ( ) allows using hierarchical names instead of relying on fixed addresses. In a URL like https:// .exemplo.com,, the host .exemplo.com needs to be resolved to an address that the client can reach. This resolution may involve local cache, corporate resolver, recursive servers, and authoritative servers.
is distributed and hierarchical. The zone responsible for a domain publishes records that describe how names should be resolved. A records associate names with IPv4 addresses; AAAA records associate them with IPv6 addresses; CNAME creates an alias for another name; TXT records transport textual information used by various mechanisms; SRV can indicate services and ports. In architectures, CNAMEs are common to decouple the public address from physical or provider infrastructure.
The Time To Live (TTL) dictates how long a response may remain in cache. A high TTL reduces queries and can improve efficiency but makes changes slower for consumers still holding outdated data. A low TTL accelerates transitions but increases queries and does not eliminate all intermediate caches. Migration and disaster recovery strategies must consider this behavior.
Split-horizon occurs when the same name returns different responses based on the origin of the query. An internal consumer may receive a private address, while an external consumer receives a public . This technique is useful but can cause confusion if tests conducted over different networks produce distinct results.
also relates to . The client typically validates whether the certificate presented by the server is valid for the requested name. Therefore, pointing a name to another alone is insufficient; the must present a compatible certificate and respond appropriately to the expected host or SNI (Server Name Indication). Certificate and name failures often occur together during migrations.
Example of resolution and connection verification
$ nslookup api.exemplo.com
Name: api.exemplo.com
Address: 203.0.113.20
$ curl -v https://api.exemplo.com/clientes
* Host api.exemplo.com:443 was resolved
* Connected to api.exemplo.com (...) port 443
Caution point
A successful ping does not confirm that an is available. ICMP may be blocked, and the depends on , routing, port, , and . Similarly, a blocked ping does not prove that HTTPS service is unavailable.
1.10 , UDP, Ports and Sockets
provides a reliable and ordered byte stream between two endpoints. Before data exchange, a connection is established through a three-way handshake: SYN, SYN-ACK, and ACK. The connection maintains sequence numbers, confirms receptions, and retransmits data as needed. These properties simplify the work of protocols such as /1.1 and /2.
Reliability comes with cost. must manage state, window sizes, retransmissions, and congestion control. Packet losses can increase latency even when the application receives all bytes at the end. Persistent connections and pools avoid repeating handshakes for each request but require careful configuration of timeouts and limits in clients, gateways, and backends.
UDP and QUIC
UDP offers datagrams without the establishment of connections and without guarantees of delivery or order within the protocol itself. This does not mean that applications on UDP are necessarily unreliable; they can implement necessary mechanisms. traditionally uses UDP in many queries, with alternatives and extensions for other scenarios.
/3 utilizes QUIC, which operates over UDP and incorporates transport and security resources. The choice allows reducing some setup costs and avoiding certain blocking effects between flows. However, the key point for a gateway professional in this chapter is to recognize that modern does not exclusively depend on in all versions.
Ports and Sockets
A port identifies a logical communication point on the host. HTTPS typically uses 443 and 80 by convention, but services can operate on other ports. The address and port pair identify a transport ; combined with source and destination endpoints and protocol, it forms a communication identification.
is an abstraction used by the operating system to allow applications to send and receive data. A server creates a , associates an address and port, and passes listening for connections. If the process is not listening, the client may receive a connection refused error. If a firewall silently discards packets, the client tends to wait until a timeout.
Distinct connections in the path
Client 10.1.5.20:53144 -> Gateway 10.2.8.10:443
ephemeral port of the service
Gateway 10.2.8.10:48720 -> Backend 10.3.9.15:8443
new backend listener connection
Architectural implications
The client-gateway and gateway- connections are typically independent. The gateway can terminate , reuse connections, and apply different timeouts. This explains why a problem may exist only on one side.
1.11 NAT, firewall, , and load balancer
NAT
Network Address Translation modifies address information, often including port information, during traffic passage. NAT allows private addresses to use a smaller set of public addresses and is common in corporate networks and cloud environments. As a result, the observed server address may be the intermediate device's address rather than the consumer's original address.
To preserve application-layer source information, proxies can add headers such as Forwarded or X-Forwarded-For. These headers require a chain of trust: accepting values directly from any client allows tampering. The border component should remove or overwrite untrusted values before passing the information.
Firewall
Firewalls apply rules to permit, reject, or discard traffic based on criteria such as address, port, protocol, and connection state. Application firewalls can analyze upper-layer protocols. In environments, different layers of firewalls may exist at the consumer, network, public edge, cluster, and host levels.
A firewall release must consider direction, origin, destination, port, and protocol. Requests like 'allow the ' are insufficient. Additionally, the normal return often depends on connection state, and traffic to identity providers, certificate validation services, or external services may also require specific rules.
Forward proxy, , and load balancer
A forward proxy, often simply called a proxy or egress proxy, acts on behalf of the client. The browser, operating system, or application knows about the intermediary and sends it a request intended for another server. The proxy decides whether to permit the outbound connection, connects to the destination, and returns the response to the consumer. Organizations use forward proxies for Internet access control, auditing, filtering, caching, and egress policy enforcement. To the destination server, the connection usually appears to originate from the proxy, which hides or replaces the client network address.
A receives requests in the name of internal servers. It can terminate , apply rules, normalize headers, compress responses, and hide topology. An has a reverse-proxy feature but adds management, security, and governance-specific functions.
With a , the consumer believes it is communicating with the published service itself. points the name to the proxy, and the proxy chooses which internal server receives the call. A forward proxy therefore represents clients and controls outbound traffic, whereas a represents servers and controls inbound traffic. Both can forward and manipulate headers, but they sit on opposite sides of the relationship and rely on different trust roots.
Comparison between a forward proxy and a reverse proxy.
Aspect
Forward proxy
Reverse proxy
Represents
A client or a network of clients
A server or a set of backends
Primary flow
Outbound traffic from the network to external services
Inbound traffic from consumers to published services
Who knows about it
The client is normally configured to use it
The client accesses the service name and may not notice the intermediary
What it hides
The source and topology of the client network
The location and number of internal servers
Frequent uses
Egress, filtering, auditing, and caching
TLS termination, routing, load balancing, WAF, and backend protection
Relationship to APIs
Controls which external APIs consumers may call
Publishes internal APIs and routes calls to the correct backends
With HTTPS, a forward proxy can create only a tunnel using CONNECT, without reading the protected traffic, or it can perform inspection when managed client devices trust a corporate CA. The latter is a sensitive operation that creates two sessions and requires governance. A can use pass-through mode and preserve to the , terminate and forward internally, or terminate and re-encrypt the call in a separate session. These modes are not equivalent and must be explicit in the trust diagram.
Load balancers distribute traffic across multiple instances to increase capacity and availability. Algorithms may consider round-robin, active connections, weights, latency, or affinity. Health checks determine which instances can receive traffic. A service may appear available in a local test but fail externally if the load balancer considers all unhealthy instances.
Common error
Terminating at the balancer does not necessarily mean that the segment up to the gateway is unprotected; re-encryption may occur. The design should register each hop, where terminates, which certificate is validated, and which context headers are trustworthy.
1.12 , HTTPS, and trust establishment
What protects — and what remains outside its scope
protects communication against unintended reading, alteration, and forgery within the considered threat model. HTTPS is transported over a protected channel by . The protocol negotiates cryptographic parameters, authenticates at least the server in common configurations, and establishes keys used to protect transmitted data.
After the handshake, records use session keys and authenticated encryption to provide confidentiality and integrity for bytes in transit on that hop. A network observer can still infer metadata such as addresses, ports, connection volume, and duration. also does not correct broken authorization, malicious payloads, compromised endpoints, secrets written to logs, or data already decrypted by the application. It protects the channel between two termination points; it does not by itself establish that the complete business journey is secure.
How the handshake establishes trust and keys
The server presents a certificate associating a public key with identities, typically names. The client verifies the signature, validity period, certificate chain, permitted usage, and name match. Trust depends on accepted certification authorities by the client. In corporate environments, certificates may be issued by public authorities or internal PKIs.
At the start, ClientHello advertises supported versions, cipher suites, key-exchange groups, and extensions. SNI carries the expected name so a shared address can select the correct certificate; ALPN negotiates /1.1, /2, or another application protocol. The server responds with the selected parameters, its certificate chain, and proof that it possesses the private key. An ephemeral exchange, normally ECDHE in modern , produces the secret from which session keys are derived without transmitting those keys over the network. Finished messages authenticate the handshake transcript and detect tampering with the negotiation.
During the handshake, the client and server negotiate compatible versions and algorithms. 1.3 simplified and modernized parts of the protocol compared to previous versions. The application should only send sensitive information after the channel is established and validated. If negotiation fails, no gateway policy can be executed because the application message has not yet been received.
1.3 removed obsolete cryptographic options, reduced plaintext handshake messages, and normally completes a new handshake in one round trip. Session resumption with PSKs or tickets reduces cost and latency, but tickets and their protection keys also need expiration and rotation. The 0-RTT mode can send data before a new handshake finishes, but it permits replay under certain conditions; it should therefore be restricted to truly safe and idempotent operations or remain disabled for sensitive APIs.
: mutual authentication at the channel
adds client authentication at the level. In addition to validating the server's certificate, the server requests and validates a certificate presented by the client. This is common in B2B and financial integrations. authenticates a technical identity linked to the certificate; business authorization may still depend on tokens, scopes, contracts, and context.
When is required, the server sends CertificateRequest with information about acceptable CAs and algorithms. The client presents its chain and produces CertificateVerify, a signature over the transcript proving possession of the corresponding private key—sending a copied certificate alone is not enough. The server validates the chain, validity, key usage, policies, and, where applicable, revocation; it then maps the subject, SAN, fingerprint, or registered data to a technical identity. That mapping must be explicit and auditable.
operations depend on a lifecycle: secure issuance, private-key storage, chain distribution, renewal before expiration, rotation without downtime, and revocation when a partner or workload is no longer trusted. Different clients should not indiscriminately share the same key. In service meshes and internal communication, workload identities and automation can reduce manual work, but they do not eliminate the need to define which CA is trusted for which purpose.
does not replace OAuth, JWT, or resource authorization. The certificate primarily answers which system possesses the key and participates in the channel; a token can represent a user, consent, audience, and scopes. In combined architectures, the gateway first associates the certificate with an authorized client, then validates the token and enforces business policies. Binding a token to the certificate, when supported by the adopted profile, also reduces the value of a stolen token outside the authorized channel.
can terminate at multiple points. An external connection might end with a WAF or load balancer, followed by another connection to the . The could create a third connection to the . Each segment has its own handshake, configuration, truststore, certificate, and risk profile. Simply stating 'the uses HTTPS' is insufficient to understand the architecture.
Example of hops
Client --TLS 1--> Load Balancer --TLS 2--> API Gateway --TLS 3--> Backend
certificate public internal mTLS optional
Each arrow represents a connection and potentially different validation.
Handshake diagnosis
Messages like certificate unknown, hostname mismatch, unknown CA, expired certificate, no shared cipher or protocol version point to different classes of failures. Capturing the error and identifying the hop are essential.
1.13 Anatomy of an Message
follows a request-response model. The request contains methods, targets, headers (when applicable), and content. The response contains status codes, headers, and content. defines semantics: a method is not just a word, and a code is not just a number. Clients, caches, proxies, and gateways make decisions based on these meanings.
The GET method requests a representation and is considered safe and idempotent in the protocol model. POST sends content for processing defined by the resource. PUT associates with creating or replacing state at the target and is idempotent. DELETE requests removal and also has idempotent semantics, though response and observable effects may vary. PATCH applies partial modifications according to the format used.
Headers carry metadata. Host or :authority identifies the destination authority; Content-Type describes the type of content sent; Accept indicates accepted representations; Authorization carries application credentials; Cache-Control directs caching; traceparent can propagate tracing context. Gateways frequently validate, remove, add, or transform headers.
Status codes 2xx indicate success; 3xx handle redirections; 4xx indicate that the request cannot be fulfilled under the presented conditions; 5xx indicate server-side or intermediary failures. The code should be interpreted with the body, headers, emitting component, and context. A 404 could mean an absent resource or unpublished gateway route.
is stateless in the sense that each request must contain the necessary information for its interpretation. Applications can build sessions using cookies or tokens, but this occurs above the basic semantics of the protocol. Corporate APIs typically prefer explicit tokens and per-request context to facilitate distribution and scalability.
Simplified HTTP Request and Response
GET /v1/clientes/123 HTTP/1.1
Host: api.exemplo.com
Accept: application/json
Authorization: Bearer <token>
X-Correlation-ID: 7ad3c8c0
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-Correlation-ID: 7ad3c8c0
{
"id": 123,
"nome": "Cliente de Exemplo"
}
Table 2 - Initial Interpretation of Common Status Codes in Gateways.
Code
Initial Interpretation
Possible origin in APIs
200
Operation completed
Backend or synthesized response by the gateway
400
Invalid request
Schema, parameter, header, or syntax issue
401
Unauthorized
Token absent/invalid or certificate not associated
403
Authorized without permission
Scope, role, contract, or policy issue
404
Resource or route not found
Gateway, backend or incorrect version
429
Rate limit exceeded
Rate limit or quota
502
Invalid upstream response
Gateway-backend failure
503
Service unavailable
No healthy instances or capacity protection
504
Upstream timeout
Backend did not respond in time
1.14 and the Concept of Resource
was defined by Roy Fielding as an architectural style for distributed hypermedia systems. An architectural style is a set of constraints that produce certain properties. combines client-server, stateless, caching, uniform interface, layered system, and optional demand-driven coding. The desired result includes scalability, visibility, and independent evolution of components.
The central concept is the resource. A resource represents something that can be identified: a customer, an account, a payment, a contract, or a collection. Consumers interact with representations of the resource, such as JSON or XML. The identifies the resource; the method expresses the intent; headers and content complete the message. This separation avoids drawing the interface only as disguised procedure calls.
Stateless means that the server should not depend on hidden session context between requests to interpret the next operation. Each request brings the necessary context. This facilitates distribution across instances and increases visibility, but can increase message size. Access tokens are an example of explicitly transported contextual information.
The uniform interface limits variations and allows intermediaries to understand the communication. Correct method semantics and self-describing representations and hypermedia make up part of the model. Many commercial APIs adopt only a subset of these restrictions. It is useful to recognize the difference between as defined academically and the colloquial use of " ".
Layered system allows inserting proxies, caches, gateways, and balancers without requiring the consumer to know the entire topology. This constraint directly connects to the world of Gateways: the client calls a public authority and does not need to know which microservice, cluster, or datacenter processes the operation.
Example of resource-oriented modeling
GET /clientes/123 retrieve customer representation
PUT /clientes/123 replace state according to contract
PATCH /clientes/123 apply partial change
DELETE /clientes/123 request removal
GET /clientes/123/contas navigate sub-resources
Be careful with verbs in the
Routes such as /consultarCliente or /deletarCliente make the interface resemble RPC. While not all uses are automatically incorrect, the design should be intentional and coherent with the chosen style.
1.15 and Platform
An is a specialized intermediary that receives consumer calls and forwards them to services. Along the way, it applies policies related to security, traffic, mediation, routing, and observability. This position allows for standardizing controls without duplicating all implementations in each service.
The gateway should not be confused with the entire Management platform. The platform may include management planes, catalogs, developer portals, analytics, product management, subscriptions, credentials, and lifecycle management. The gateway is the runtime or data plane component that processes traffic. Different products use their own names and separations, but the conceptual distinction is useful.
Gateway security can include key validation, JWTs, OAuth 2.0, , signature verification, allow lists, and protection against malformed content. Traffic control can include rate limiting, quotas, spike arrest, and circuit breaking. Mediation may transform headers, paths, and formats. Observability collects logs, metrics, and traces for operation and auditing.
Centralization brings benefits and risks. Consistent policies increase governance, but the gateway can become a critical capacity and availability point. Excessively complex rules elevate latency and complicate maintenance. Deep business logic in the gateway creates coupling and reduces responsibility clarity. The design should maintain balance between cross-cutting controls and domain.
Axway provides management, delivery, and security features with policies and administration components. Azure Management offers a managed platform with gateway, management plane, and portal. Despite product differences, the fundamentals of this chapter apply to both: listeners, certificates, , upstreams, policies, identity, logs, and capacity.
Figure 3 - Typically cross-cutting responsibilities are concentrated in the .
Responsibility Boundary
The gateway can validate that a token contains the appropriate scope, but the remains responsible for authorization rules tied to the data and domain, such as verifying whether the authenticated client may access that specific account.
1.16 End-to-End Journey of an Call
Consider a corporate application that sends GET https:// .exemplo.com/v1/clientes/123. Before sending the message, the client library interprets the , identifies the HTTPS scheme, host, default port 443, and path. It performs name resolution, possibly using caches from the process, operating system, and configured resolver.
After obtaining an address, the client initiates a transport connection. In /1.1 or /2 over , a three-way handshake occurs. Then, the handshake begins. The client informs capabilities, version, and server name; the presents the certificate and negotiates keys. If validation fails, the operation terminates before an useful request exists for the gateway.
With the channel established, the client sends method, path, headers, and body. A border component may receive the connection, apply application firewall rules, limit size, and forward the message. The selects the published based on host, path, method, and configuration. Policies can validate client certificate, token, scope, schema, and consumption limits.
If the request is accepted, the gateway determines the , builds or reuses a connection, and sends an message. The performs additional authentication or domain authorization, queries dependencies, and produces response. The gateway receives this response, may transform it, remove internal headers, record metrics, and return it to the consumer.
Responses traverse independent connections. The does not necessarily know the original client address, nor does the client know the address. Controlled headers can propagate correlation IDs, technical identity, and origin information. Each hop must have clear contracts to avoid spoofing, loss of context, and exposure of internal details.
In case of failure, the component detecting the problem may generate the response. A 401 can be produced by the gateway policy without calling the . A 502 can result from connection failure. A 500 can come from the and only traverse through the gateway. Identifying the real sender is one of the key troubleshooting skills.
Figure 4 - Main components along the end-to-end journey.
Detailed sequence
The application constructs , headers, content, and its timeout settings.
The host is resolved by ; the client chooses one of the returned addresses.
Routing and network rules allow or prevent reaching the .
or QUIC connection is established.
negotiates parameters, validates certificates, and creates session keys.
The border receives the request and may apply initial protection.
The gateway identifies the and executes ingress policies.
Credentials are locally validated or with identity systems.
The gateway selects the and forwards the request.
The executes business rules and accesses dependencies.
The response returns to the gateway, which applies egress policies.
Metrics, logs, and traces are recorded; the response returns to the client.
Operational Question
Which of these steps did the call stop at? This question is more useful than 'The is down?' because it transforms a broad symptom into verifiable hypotheses.
1.17 Layered Troubleshooting
Efficient troubleshooting starts with evidence, not changes. Record timestamps in time zone, , consumer, method, correlation ID, code, duration, and full message. Compare calls that fail with those that work. Recent changes, certificate updates, route adjustments, policy modifications, reboots, or credential refreshes help prioritize hypotheses but do not replace validation.
Investigation can proceed from bottom to top. First, does the name resolve to the expected address? Second, is connectivity established to the port? Third, did handshake complete and validate certificate? Fourth, does request reach ? Fifth, which policy or route is selected? Sixth, does respond? Seventh, does business rule conclude? This order avoids analyzing payloads when connections do not exist.
It's also necessary to observe chain timeouts. The consumer timeout should be consistent with the edge, gateway, and timeouts. If the gateway waits 60 seconds but the load balancer times out in 30, the effective limit is 30. Automatic retries can multiply load and transform latency into unavailability. Timeouts, retries, and circuit breakers need to be designed together.
Logs should allow correlation between hops. A stable correlation ID facilitates transaction tracking while trace IDs and spans show dependencies and duration. Be cautious with sensitive data: tokens, private certificates, passwords, and personal payloads should not be indiscriminately logged. Observability requires balancing diagnosis, security, privacy, and cost.
The gateway offers a privileged point of observation but does not see everything. If handshake fails before the listener, there may be no policy log. If accepts connection internally, the gateway only observes timeouts. If client cancels request, can continue processing. Interpretation requires combining sources.
Table 3 - Initial troubleshooting matrix.
Layer/Stage
Test or Evidence
Common Failures
DNS
nslookup/dig, cache, expected record
NXDOMAIN, old IP, split DNS
Network
route, firewall, connection to port
timeout, reset, connection refused
TLS
openssl/curl -v, chain and name
Unknown CA, expired, mismatch
HTTP
method, path, headers, size
400, 404, 405, 413
Gateway
policy trace, selected API
401, 403, 429, incorrect route
Upstream
pool, health check, backend connection
502, 503, 504
Application Layer
logs, trace, database and dependencies
500, sluggishness, business rule
Best practice
Before restarting a component, preserve evidence. Restarts can alleviate symptoms and erase useful state for analysis in critical environments, follow incident management, change control, and communication procedures defined by the organization.
1.18 Application in Corporate and Banking Environments
Financial institutions operate APIs with high confidentiality, integrity, availability, traceability, and segregation requirements. A call may traverse public internet, private networks, security zones, multiple gateways, identity providers, legacy systems, and cloud platforms. Each boundary adds controls and also operational complexity.
is frequently used to authenticate technical participants and establish trust between organizations or internal layers. OAuth 2.0 and tokens can represent delegated authorization, scopes, and client context. The use of both together is not simple redundancy: protects and authenticates the technical channel/participant, while tokens may carry application authorization and consent as per the ecosystem.
Corporate gateways apply common patterns to avoid each implementing validation of certificates, rate limiting, quotas, and logging differently. However, policies should be versioned, tested, and observed like software. A change in truststore, algorithm, timeout, or transformation can affect many APIs at once.
Hybrid architectures may use an on-premises gateway and another in the cloud. A request may pass through Axway at the corporate edge and Azure APIM near services in Azure, or vice versa depending on the design. In these cases, it is essential to define which layer authenticates, authorizes, which headers can traverse, where terminates, and how correlation IDs are preserved.
risk does not limit to external attacks. Incorrect configuration, incomplete inventory, excessive credentials, insecure dependencies, and third-party consumption may expose data and operations. The OWASP Security Top 10 and NIST SP 800-228 provide structures for studying vulnerabilities and controls in pre-runtime and runtime phases.
Understanding layers also improves communication between teams. Instead of attributing a generic failure to the gateway, networks can confirm path and firewall; security can validate certificates and trust; identity can analyze tokens; platform can verify policies and ; application can investigate business rules. A common vocabulary reduces resolution time.
Simplified banking scenario
Partner presents certificate to the gateway. The gateway validates the chain, validity, and registered identity. It then validates the access token and its scopes. The also verifies authorization on the requested resource. Logs record the transaction without storing secrets.
Chapter Summary
APIs depend on a chain formed by , network, transport, , , gateway, and
.
Internet, Web, , , and are related concepts but distinct entities.
The IETF and Editor define and publish many protocols; manufacturers document their
implementations.
separates responsibilities and allows layers to evolve
relatively independently.
associates names with resolution information; handles addressing and routing;
provides a reliable byte stream; protects the channel; defines application messages and semantics.
An is the data plane that applies policies and routes traffic; Management
encompasses a broader lifecycle.
Client-to-gateway and gateway-to- connections are independent and may have different certificates,
timeouts, and failure modes.
Layered troubleshooting begins with evidence and identifies the exact stage where the
transaction stopped.
Review Questions
Explain why Internet and Web are not synonymous.
What is the difference between an and a ?
Why does the manufacturer's documentation not replace an ?
What occurs during and decapsulation?
How does the layer model aid in fault investigation?
What is the difference between routing and routing?
How does TTL influence migrations and failover?
Why a refused connection and timeout suggest different hypotheses?
What is the difference between the client-gateway and gateway- connections?
What does protect and what it doesn't solve alone?
Why can and OAuth be used together?
How to interpret an code produced by the gateway instead of the ?
Which responsibilities are appropriate for the gateway and which should remain in the ?
How do unaligned timeouts between components affect a call?
Describe, in order, the complete HTTPS request lifecycle journey.
Case Studies
Case 1 - Certificate swapped during migration
A team changes the CNAME of .exemplo.com to a new load balancer. Some consumers access normally while others receive hostname or untrusted chain errors. seems correct in tests conducted by the responsible team.
Analyze possible causes considering cache, split-horizon, SNI, certificate presented by the new , intermediate chain and different truststores. List evidence you would collect before reconfiguring again.
Case 2 - Intermittent 504
An exhibits intermittent 504 during peak hours. The logs some completed operations after 40 seconds, but the gateway has a timeout of 30 seconds. The client performs two automatic retries.
Explain how timeouts and retries can increase load and produce duplicate operations. Propose a set of analyses involving latency, idempotence, gateway capacity, gateway limit, and consumer behavior.
Case 3 - Only 401 in One Environment
The same token works on the sandbox environment, but receives a 401 error in production. The format of the token seems correct and the has the same path in both environments.
Investigate possible differences in issuer, audience, signature key, clock skew, scope, policy, chain, and product. Explain what data can be securely recorded to compare the two executions.
Essential Glossary
Term
Definition within the context of the chapter
API
An interface that defines how software components may use capabilities provided by another component.
API Gateway
A specialized intermediary that receives, protects, mediates, and forwards API calls.
Backend/Upstream
The destination service to which the gateway forwards the request.
DNS
Distributed name system used for resolving names and other associated data.
Encapsulation
Process in which each layer adds control information to the data.
Endpoint
A point of communication identified by information such as scheme, host, port, and path.
HTTP
Application Protocol with a request/response model and standardized semantics.
IP
The protocol responsible for addressing and forwarding datagrams between networks.
mTLS
Transport Layer Security (TLS) with client certificate authentication, in addition to server authentication.
Reverse proxy
An intermediary that receives requests on behalf of internal servers.
Representational State Transfer (REST)
A style of architectural pattern for distributed hypermedia systems.
RFC
Published document in the Request for Comments series, which may register standards, practices, or informational material.
Socket
An abstraction used by applications to communicate over a network.
TCP
A protocol that provides reliable and ordered byte stream transmission.
TLS
A protocol that secures communications and establishes cryptographic trust.
Uniform Resource Identifier (URI)
Compact identifier for an abstract or physical resource.
Official references and recommended readings
IETF - About RFCs. https://www.ietf.org/process/rfcs/ - Overview of the role of RFCs and the IETF process.
Editor. https://www. -editor.org/ - Research and status of RFCs.
9293 - Transmission Control Protocol. https://www. -editor.org/ /rfc9293 - Consolidated specification of .
Roy Fielding - Architectural Style. https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm - Chapter of the dissertation describing .
NIST SP 800-228. https://csrc.nist.gov/pubs/sp/800/228/final - Guidelines for Security in Cloud-Native Systems.
OWASP Security Project. https://owasp.org/www-project- -security/ - Risks and security materials for APIs.
Microsoft - Azure Management concepts. https://learn.microsoft.com/azure/ -management/ -management-key-concepts - Concepts and components of Azure Management.
Microsoft - Management gateway overview. https://learn.microsoft.com/azure/ -management/ -management-gateways-overview - Role of the gateway in the data plane.
Axway - Introduction to . https://docs.axway.com/bundle/axway-open-docs/page/docs/api_mgmt_overview/api_mgmt_components/apigateway/index.html - Official Overview of Axway .
