API Design Best Practices

Sealed classes restrict a type hierarchy, records provide immutable DTOs, pattern matching eliminates casts, modules enforce encapsulation, and reflection powers frameworks – together they build type-safe, modern banking APIs.

A DTO is a purpose-built data carrier that shapes exactly what crosses the API boundary, decoupling the contract from the entity and keeping secrets in and clutter out.

Entity persists to a table and stays internal, DTO transports data across boundaries with validation, POJO is a framework-free object that may carry domain logic.

Returning a JPA entity leaks secret columns, couples the API to the schema, triggers lazy-loading crashes, and blocks versioning, so always map to a DTO at the boundary.

MapStruct generates mapping code at compile time, so it is as fast and explicit as handwritten code but without the boilerplate, and it fails the build on mapping mistakes instead of failing at runtime like ModelMapper.

JsonView tags fields with named views so one class serializes different subsets per endpoint, avoiding near-identical DTOs, but a separate DTO wins when the shape, computed values, or combined sources differ.

The API is the language-neutral contract a service exposes; the SDK is a language-specific library that wraps that contract with auth, retries, serialization, and typed methods.

Avoid verbs in URLs, inconsistent naming, no versioning, unpaginated lists, leaked internal IDs, missing headers, and 200-for-everything; a good API uses noun resources, correct methods and status codes, versioning, pagination, stable IDs, and honest errors.

GraphQL lets the client ask for exactly the fields it needs in one request against a typed schema, curing over-fetching and under-fetching; use it for diverse connected data, and REST for simple cacheable resources.

gRPC is binary Protocol Buffers over HTTP/2 with generated typed stubs and streaming, ideal for fast internal service-to-service calls, while REST wins for simple, readable, ubiquitous public APIs.

Unary is one-to-one, server streaming is one request to many responses, client streaming is many requests to one response, and bidirectional streaming is both sides streaming on one open call.

Use org.json for quick structural conversion and Jackson XmlMapper plus ObjectMapper when you want type-safe, annotation-controlled conversion through a Java object.

Parse both JSON documents into trees and compare the trees, because raw-string comparison fails on key order, whitespace, and formatting even when the data is identical.

Short polling asks repeatedly and wastes calls, long polling holds the request until data arrives, SSE is a one-way server-to-client stream, and WebSocket is a full two-way channel on one connection.

Use WebSocket when the client must send data back in real time (chat, gaming, trading); use SSE when the server only pushes to the client (notifications, tickers, dashboards), because SSE is simpler and auto-reconnects.

Secure a REST API with layered defences: HTTPS, JWT/OAuth2 authentication, RBAC/scope authorization, input validation, rate limiting, secret management, and audit logging that never leaks secrets.

Log who did what to which target, when, under which correlation ID, and with what outcome, for every mutation including the ones you denied.

Strategy swaps behaviour behind an interface, Builder assembles complex objects readably, Observer fans out events to listeners, Circuit Breaker fails fast on a sick dependency, DTO shields the API from the entity, and SOLID holds it all together.

HPP is sending the same parameter twice so your security layer and your business layer read different values and the attacker slips through the gap.

A cookie is a small tag the browser carries and can tamper with; a session is the real state the server keeps safely, identified by a session ID sent in a cookie.

REST is simple readable JSON over HTTP for public and cacheable APIs, gRPC is fast binary over HTTP/2 for internal typed service calls, and GraphQL is a flexible single-endpoint query language where the client picks the exact shape.

The WebSocket handshake is an HTTP upgrade request answered with 101 Switching Protocols, after which the same connection carries free two-way WebSocket frames instead of HTTP.