Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
REST API best practices in 2026 are still grounded in HTTP semantics: choose methods whose behavior matches their meaning, make retries safe, and keep the API contract aligned with what the service actually does. The important updates are to use RFC 9457 for machine-readable problem responses, treat OpenAPI as an operational contract, and choose Spring’s HTTP clients according to the application’s programming model.
What actually changed—and what did not
There is no wholesale replacement for REST conventions. RFC 9110 remains the foundation for HTTP method behavior. RFC 9457, published in July 2023, supersedes RFC 7807 for HTTP Problem Details. OpenAPI continues to support documentation, code-generation, and testing workflows; the specification version and tooling must work together. In Spring applications, the practical choice between outbound clients is based on whether the application is imperative or reactive.
These are updates to how teams implement and maintain an API, not a new definition of REST. In particular, neither RFC 9457 nor OpenAPI 3.2.1 should be described as a standard that first appeared in 2026.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Design methods around their HTTP semantics
A method is part of the API contract, not just a label on a route. RFC 9110 defines GET, HEAD, OPTIONS, and TRACE as safe: the client is not asking the server to change the resource’s state. A GET endpoint should therefore not perform an unsafe action such as placing an order or changing an account setting. A client, proxy, or crawler may make a safe request under the assumption that it does not cause that kind of change.
PUT and DELETE are idempotent, as are safe methods. Idempotency means that repeating the same request has the same intended effect as making it once; it does not require identical response bodies or status codes on every attempt. POST is not inherently idempotent. An API may implement an operation with repeat-safe behavior, but clients should not assume that from the method name alone.
Make retries an explicit design decision
A timeout after a request has been sent does not establish that the server failed to apply it. The server may have completed the operation while the response was lost. RFC 9110 says a client should not automatically retry a non-idempotent request unless it can establish that the operation is actually safe to repeat or detect that the original request was never applied.
For operations where duplicate execution would matter, define an application-level safeguard. For example, a service can accept a client-supplied operation identifier and record the result so a repeat with that identifier can be recognized. That behavior is an API design choice, not a guarantee supplied by HTTP itself: document the identifier’s scope, retention period, and what the client receives on a repeat. For naturally idempotent operations, ensure the implementation really preserves the intended effect when requests are repeated.
Use RFC 9457 for machine-readable HTTP problems
RFC 9457 defines a standard format for describing an HTTP problem, commonly returned as JSON with the media type application/problem+json. It is useful when a status code alone does not give a client enough information to understand an API-specific failure. The response can carry a stable problem type and actionable details while preserving the HTTP status as the primary indication of the outcome.
Rank #3
Do not use a problem response as a debugging dump. RFC 9457 explicitly cautions that problem details describe the HTTP interface, not the implementation behind it. Avoid stack traces, secrets, internal hostnames, database messages, and details that would help an attacker. A client-facing message should explain what the caller can do; diagnostic context belongs in protected server-side logs.
Spring MVC example
Spring Framework supports Problem Details in MVC. A controller-advice class can extend ResponseEntityExceptionHandler for framework exception handling and add application-specific problem responses. The following fragment illustrates a custom not-found problem; the exception class and domain lookup are application-specific.
@ControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {
@ExceptionHandler(WidgetNotFoundException.class)
public ProblemDetail handleWidgetNotFound(WidgetNotFoundException ex) {
ProblemDetail problem = ProblemDetail.forStatusAndDetail(
HttpStatus.NOT_FOUND,
"The requested widget does not exist."
);
problem.setTitle("Widget not found");
problem.setType(URI.create("https://api.example.com/problems/widget-not-found"));
return problem;
}
}Use a stable, documented problem type when clients need to distinguish a specific condition. Keep the detail suitable for the caller, and add only extensions that have a defined meaning for clients. Do not expose an exception’s raw message by default: it may contain implementation details.
Free tools Windows power users keep installed
One-click scans. No signup required.
Make the OpenAPI description match the running API
OpenAPI is more than a page of endpoint documentation. Its descriptions can drive reference documentation, client generation, and tests. Specify paths and methods, request and response schemas, relevant status codes, and security requirements. A description that drifts from runtime behavior can generate clients that compile but make incorrect assumptions.
OpenAPI 3.2.1 is a specification version identified in the official specification material relevant to this article. That does not mean every validator, generator, or client library supports it. Select a version compatible with the actual toolchain and publish the version your API contract uses.
Choose how the contract is maintained
- Contract-first: maintain the OpenAPI description as a reviewed API artifact, then implement against it. This makes the contract explicit and can support governance before code is deployed; the team must keep implementation and description aligned.
- Generated from Spring: springdoc-openapi can inspect Spring configuration, classes, and annotations to generate an OpenAPI description. This reduces separate authoring, but generated output still needs review for completeness and accuracy. Its major releases align with Spring Boot major versions, so check compatibility before upgrading.
Neither approach removes the need to verify the contract against actual behavior. Decide which artifact is authoritative, include contract checks in the development workflow, and review generated or hand-authored changes alongside API changes.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choose the Spring outbound client for the application model
For imperative applications, Spring Boot’s reference identifies RestClient as the functional choice. For reactive applications using WebFlux, it points to WebClient. Choose based on the execution model, dependencies, and call patterns already used by the application—not because one client is universally better.
// Imperative call with RestClient
String response = restClient.get()
.uri("/catalog/items/{id}", itemId)
.retrieve()
.body(String.class);// Reactive call with WebClient
Mono<String> response = webClient.get()
.uri("/catalog/items/{id}", itemId)
.retrieve()
.bodyToMono(String.class);These fragments show the different call styles; they are not a complete application configuration or a tested sample for every Spring release. Confirm the APIs and dependency versions against the Spring Boot version your service actually uses. The Spring Boot reference identified version 4.1.1 as latest stable in the material consulted for this article, but release status changes; verify the current release before adopting a version number in project documentation or code.
Quick Recap
Practical review checklist
- Does each method’s externally visible behavior match its HTTP semantics?
- Can a client distinguish an operation that was not applied from one that may have completed before a timeout?
- Are retry rules based on idempotency and explicit safeguards rather than assumptions about network failures?
- Do error responses use a stable, client-safe problem format where additional machine-readable context is needed?
- Does the OpenAPI contract describe the current paths, schemas, responses, and security requirements?
- Are OpenAPI tooling and the selected Spring client compatible with the project’s versions and programming model?
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
