Package org.apache.juneau.http

Annotation Interface Url

@Documented @Target(PARAMETER) @Retention(RUNTIME) @Inherited public @interface Url
REST request dynamic-URL annotation.

Identifies a method parameter on a REST proxy interface whose value supplies the entire request URL (or a root-relative URL) for that single call — the Retrofit @Url pattern.

Arguments of client-side @Remote-annotated interfaces

When the bound argument is non-null and non-blank, its string value becomes the effective URL for that invocation, overriding the interface/method-declared path resolution:

  • If the value contains a scheme (e.g. "http://other-host/path") it is treated as an absolute URL that replaces the whole computed endpoint and bypasses the client root URL.
  • If the value has no scheme (e.g. "/other/path") it is treated as a relative URL resolved against the client root URL only — not against the interface Remote.path() (matching Retrofit "endpoint replacement").

Any {var} tokens in the supplied value are still filled by the call's @Path parameters, so a caller-supplied URL may contain path templates. An @Url argument takes precedence over Remote.path() + @RemoteOp(path=...) and over any declarative baseUrl override.

Example:

@Remote(path="/api") public interface MyProxy { // Caller chooses the endpoint at runtime. @RemoteGet String fetch(@Url String url); }

Notes:
  • At most one @Url parameter is allowed per method (validated at proxy-build time).
  • A null or blank @Url argument is rejected with an IllegalArgumentException.
  • Only http/https schemes are permitted; other schemes (e.g. file:, gopher:) are rejected (SSRF guardrail).
  • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)), with the same http/https-only scheme guard on both.
See Also:
Since:
9.2.1