@RemoteOp

The @RemoteOp annotation is applied to methods of @Remote-annotated interfaces to identify REST endpoints.

RemoteOpmethodpathreturns

Specialized sub-annotations are provided for common HTTP methods:

RemoteGetRemotePostRemotePutRemotePatchRemoteDelete

@RemoteOp(method/path)

The HTTP method and path are mapped to a Java method using the method and path annotations.

Example

@Remote
public interface PetStore {

    // GET /pets/{petId}
    @RemoteGet("/pets/{petId}")
    Pet getPet(@Path("petId") int id);
}

The Java method name can be anything.

Inferred method/path

In such cases, method and path annotations are optional if you follow certain naming conventions on your method that identify the method and path. For example, the getPet method below defaults to GET /pet:

@Remote
public interface PetStore {

    // GET /pet
    @RemoteOp
    Pet getPet(...);
}

In such cases, the @RemoteOp annotation is optional. Method names matching the following pattern are assumed to be implying the HTTP method name:

(get|put|post|delete|options|head|connect|trace|patch).*

do(?i)(get|put|post|delete|options|head|connect|trace|patch)

Examples

Java method name	Inferred HTTP method	Inferred HTTP path
getPet()	GET	/pet
get()	GET	/
postPet()	POST	/pet
fooPet()	[default]	/fooPet
doGet()	GET	/
doGET()	GET	/
doFoo()	[default]	/doFoo

@RemoteOp(returns)

The return type of the Java methods can be any of the following:

• void/Void

  • Don't parse any response.
  • The response is discarded entirely, so a void method never throws on an error HTTP status. Use a non-void return type (with a declared HTTP-response exception in the throws clause, or throwOnError) if you need error handling.

• Any parseable POJO

  • The body of the response will be converted to the POJO using the parser defined on the RestClient based on the Content-Type of the response.

• Any @Response-annotated type

  • For returning custom response objects with status codes and headers.

• HttpResponse

  • Returns the raw HttpResponse returned by the inner HttpClient.

• Reader

  • Returns access to the raw reader of the response.

• InputStream

  • Returns access to the raw input stream of the response.

• Future or CompletableFuture

  • Of any type on this list for asynchronous processing.

If you're only interested in the HTTP status code of the response, you can use the returns annotation with a value of STATUS:

Example

@Remote
public interface PetStore {

    // POST /pets
    // Returns HTTP status code.
    @RemotePost(returns=STATUS)
    int pets(...);
}

If your RestClient does not have a parser associated with it, then the value is converted directly from a String using the rules defined in POJO Categories.

Method-level request policy

In addition to method/path/returns, @RemoteOp (and the @RemoteGet/@RemotePost/@RemotePut/@RemotePatch/@RemoteDelete variants) supports the same request-policy members as @Remote: headers, queryData, formData, accept, contentType, baseUrl, timeout, retries, retryNonIdempotent, and throwOnError. A method-level value overrides the interface-level value, and constant headers/queryData/formData entries are merged with the interface-level entries (method-level wins on a name collision). As of 10.0.0 these are honored by both the classic and next-generation proxy engines.

An additional call-time endpoint override is available via the @Url parameter annotation, which replaces the resolved URL for that single call (it takes precedence over baseUrl, and — like baseUrl — must resolve to an http/https URL).

Example

@Remote(path="/petstore")
public interface PetStore {

    // Per-operation Accept + retry policy, overriding any interface-level defaults.
    @RemoteGet(path="/pets", accept="application/json", retries=3)
    Pet[] getPets();

    // Call-time endpoint override.
    @RemoteGet
    Pet[] getPetsFrom(@Url String url);
}

See Also

@Remote - Interface-level request policy and cross-engine parity notes.