Interface RestOperations

All Known Implementing Classes:
RestTemplate

public interface RestOperations
Interface specifying a basic set of RESTful operations.

Implemented by RestTemplate. Not often used directly, but a useful option to enhance testability, as it can easily be mocked or stubbed.

Since:
3.0
Author:
Arjen Poutsma, Juergen Hoeller
See Also:
  • Method Details

    • getForObject

      @Nullable <T> T getForObject(String url, Class<T> responseType, Object... uriVariables) throws RestClientException
      Retrieve a representation by doing a GET on the specified URL. The response (if any) is converted and returned.

      URI Template variables are expanded using the given URI variables, if any.

      Parameters:
      url - the URL
      responseType - the type of the return value
      uriVariables - the variables to expand the template
      Returns:
      the converted object
      Throws:
      RestClientException
    • getForObject

      @Nullable <T> T getForObject(String url, Class<T> responseType, Map<String,?> uriVariables) throws RestClientException
      Retrieve a representation by doing a GET on the URI template. The response (if any) is converted and returned.

      URI Template variables are expanded using the given map.

      Parameters:
      url - the URL
      responseType - the type of the return value
      uriVariables - the map containing variables for the URI template
      Returns:
      the converted object
      Throws:
      RestClientException
    • getForObject

      @Nullable <T> T getForObject(URI url, Class<T> responseType) throws RestClientException
      Retrieve a representation by doing a GET on the URL. The response (if any) is converted and returned.
      Parameters:
      url - the URL
      responseType - the type of the return value
      Returns:
      the converted object
      Throws:
      RestClientException
    • getForEntity

      <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Object... uriVariables) throws RestClientException
      Retrieve an entity by doing a GET on the specified URL. The response is converted and stored in a ResponseEntity.

      URI Template variables are expanded using the given URI variables, if any.

      Parameters:
      url - the URL
      responseType - the type of the return value
      uriVariables - the variables to expand the template
      Returns:
      the entity
      Throws:
      RestClientException
      Since:
      3.0.2
    • getForEntity

      <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Map<String,?> uriVariables) throws RestClientException
      Retrieve a representation by doing a GET on the URI template. The response is converted and stored in a ResponseEntity.

      URI Template variables are expanded using the given map.

      Parameters:
      url - the URL
      responseType - the type of the return value
      uriVariables - the map containing variables for the URI template
      Returns:
      the converted object
      Throws:
      RestClientException
      Since:
      3.0.2
    • getForEntity

      <T> ResponseEntity<T> getForEntity(URI url, Class<T> responseType) throws RestClientException
      Retrieve a representation by doing a GET on the URL. The response is converted and stored in a ResponseEntity.
      Parameters:
      url - the URL
      responseType - the type of the return value
      Returns:
      the converted object
      Throws:
      RestClientException
      Since:
      3.0.2
    • headForHeaders

      HttpHeaders headForHeaders(String url, Object... uriVariables) throws RestClientException
      Retrieve all headers of the resource specified by the URI template.

      URI Template variables are expanded using the given URI variables, if any.

      Parameters:
      url - the URL
      uriVariables - the variables to expand the template
      Returns:
      all HTTP headers of that resource
      Throws:
      RestClientException
    • headForHeaders

      HttpHeaders headForHeaders(String url, Map<String,?> uriVariables) throws RestClientException
      Retrieve all headers of the resource specified by the URI template.

      URI Template variables are expanded using the given map.

      Parameters:
      url - the URL
      uriVariables - the map containing variables for the URI template
      Returns:
      all HTTP headers of that resource
      Throws:
      RestClientException
    • headForHeaders

      HttpHeaders headForHeaders(URI url) throws RestClientException
      Retrieve all headers of the resource specified by the URL.
      Parameters:
      url - the URL
      Returns:
      all HTTP headers of that resource
      Throws:
      RestClientException
    • postForLocation

      @Nullable URI postForLocation(String url, @Nullable Object request, Object... uriVariables) throws RestClientException
      Create a new resource by POSTing the given object to the URI template, and return the value of the Location header. This header typically indicates where the new resource is stored.

      URI Template variables are expanded using the given URI variables, if any.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      The body of the entity, or request itself, can be a MultiValueMap to create a multipart request. The values in the MultiValueMap can be any Object representing the body of the part, or an HttpEntity representing a part with body and headers.

      Parameters:
      url - the URL
      request - the Object to be POSTed (may be null)
      uriVariables - the variables to expand the template
      Returns:
      the value for the Location header
      Throws:
      RestClientException
      See Also:
    • postForLocation

      @Nullable URI postForLocation(String url, @Nullable Object request, Map<String,?> uriVariables) throws RestClientException
      Create a new resource by POSTing the given object to the URI template, and return the value of the Location header. This header typically indicates where the new resource is stored.

      URI Template variables are expanded using the given map.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request

      The body of the entity, or request itself, can be a MultiValueMap to create a multipart request. The values in the MultiValueMap can be any Object representing the body of the part, or an HttpEntity representing a part with body and headers.

      Parameters:
      url - the URL
      request - the Object to be POSTed (may be null)
      uriVariables - the variables to expand the template
      Returns:
      the value for the Location header
      Throws:
      RestClientException
      See Also:
    • postForLocation

      @Nullable URI postForLocation(URI url, @Nullable Object request) throws RestClientException
      Create a new resource by POSTing the given object to the URL, and return the value of the Location header. This header typically indicates where the new resource is stored.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      The body of the entity, or request itself, can be a MultiValueMap to create a multipart request. The values in the MultiValueMap can be any Object representing the body of the part, or an HttpEntity representing a part with body and headers.

      Parameters:
      url - the URL
      request - the Object to be POSTed (may be null)
      Returns:
      the value for the Location header
      Throws:
      RestClientException
      See Also:
    • postForObject

      @Nullable <T> T postForObject(String url, @Nullable Object request, Class<T> responseType, Object... uriVariables) throws RestClientException
      Create a new resource by POSTing the given object to the URI template, and return the representation found in the response.

      URI Template variables are expanded using the given URI variables, if any.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      The body of the entity, or request itself, can be a MultiValueMap to create a multipart request. The values in the MultiValueMap can be any Object representing the body of the part, or an HttpEntity representing a part with body and headers.

      Parameters:
      url - the URL
      request - the Object to be POSTed (may be null)
      responseType - the type of the return value
      uriVariables - the variables to expand the template
      Returns:
      the converted object
      Throws:
      RestClientException
      See Also:
    • postForObject

      @Nullable <T> T postForObject(String url, @Nullable Object request, Class<T> responseType, Map<String,?> uriVariables) throws RestClientException
      Create a new resource by POSTing the given object to the URI template, and return the representation found in the response.

      URI Template variables are expanded using the given map.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      The body of the entity, or request itself, can be a MultiValueMap to create a multipart request. The values in the MultiValueMap can be any Object representing the body of the part, or an HttpEntity representing a part with body and headers.

      Parameters:
      url - the URL
      request - the Object to be POSTed (may be null)
      responseType - the type of the return value
      uriVariables - the variables to expand the template
      Returns:
      the converted object
      Throws:
      RestClientException
      See Also:
    • postForObject

      @Nullable <T> T postForObject(URI url, @Nullable Object request, Class<T> responseType) throws RestClientException
      Create a new resource by POSTing the given object to the URL, and return the representation found in the response.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      The body of the entity, or request itself, can be a MultiValueMap to create a multipart request. The values in the MultiValueMap can be any Object representing the body of the part, or an HttpEntity representing a part with body and headers.

      Parameters:
      url - the URL
      request - the Object to be POSTed (may be null)
      responseType - the type of the return value
      Returns:
      the converted object
      Throws:
      RestClientException
      See Also:
    • postForEntity

      <T> ResponseEntity<T> postForEntity(String url, @Nullable Object request, Class<T> responseType, Object... uriVariables) throws RestClientException
      Create a new resource by POSTing the given object to the URI template, and return the response as ResponseEntity.

      URI Template variables are expanded using the given URI variables, if any.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      The body of the entity, or request itself, can be a MultiValueMap to create a multipart request. The values in the MultiValueMap can be any Object representing the body of the part, or an HttpEntity representing a part with body and headers.

      Parameters:
      url - the URL
      request - the Object to be POSTed (may be null)
      uriVariables - the variables to expand the template
      Returns:
      the converted object
      Throws:
      RestClientException
      Since:
      3.0.2
      See Also:
    • postForEntity

      <T> ResponseEntity<T> postForEntity(String url, @Nullable Object request, Class<T> responseType, Map<String,?> uriVariables) throws RestClientException
      Create a new resource by POSTing the given object to the URI template, and return the response as HttpEntity.

      URI Template variables are expanded using the given map.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      The body of the entity, or request itself, can be a MultiValueMap to create a multipart request. The values in the MultiValueMap can be any Object representing the body of the part, or an HttpEntity representing a part with body and headers.

      Parameters:
      url - the URL
      request - the Object to be POSTed (may be null)
      uriVariables - the variables to expand the template
      Returns:
      the converted object
      Throws:
      RestClientException
      Since:
      3.0.2
      See Also:
    • postForEntity

      <T> ResponseEntity<T> postForEntity(URI url, @Nullable Object request, Class<T> responseType) throws RestClientException
      Create a new resource by POSTing the given object to the URL, and return the response as ResponseEntity.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      The body of the entity, or request itself, can be a MultiValueMap to create a multipart request. The values in the MultiValueMap can be any Object representing the body of the part, or an HttpEntity representing a part with body and headers.

      Parameters:
      url - the URL
      request - the Object to be POSTed (may be null)
      Returns:
      the converted object
      Throws:
      RestClientException
      Since:
      3.0.2
      See Also:
    • put

      void put(String url, @Nullable Object request, Object... uriVariables) throws RestClientException
      Create or update a resource by PUTting the given object to the URI.

      URI Template variables are expanded using the given URI variables, if any.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      Parameters:
      url - the URL
      request - the Object to be PUT (may be null)
      uriVariables - the variables to expand the template
      Throws:
      RestClientException
      See Also:
    • put

      void put(String url, @Nullable Object request, Map<String,?> uriVariables) throws RestClientException
      Creates a new resource by PUTting the given object to URI template.

      URI Template variables are expanded using the given map.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      Parameters:
      url - the URL
      request - the Object to be PUT (may be null)
      uriVariables - the variables to expand the template
      Throws:
      RestClientException
      See Also:
    • put

      void put(URI url, @Nullable Object request) throws RestClientException
      Creates a new resource by PUTting the given object to URL.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      Parameters:
      url - the URL
      request - the Object to be PUT (may be null)
      Throws:
      RestClientException
      See Also:
    • patchForObject

      @Nullable <T> T patchForObject(String url, @Nullable Object request, Class<T> responseType, Object... uriVariables) throws RestClientException
      Update a resource by PATCHing the given object to the URI template, and return the representation found in the response.

      URI Template variables are expanded using the given URI variables, if any.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      NOTE: The standard JDK HTTP library does not support HTTP PATCH. You need to use e.g. the Apache HttpComponents request factory.

      Parameters:
      url - the URL
      request - the object to be PATCHed (may be null)
      responseType - the type of the return value
      uriVariables - the variables to expand the template
      Returns:
      the converted object
      Throws:
      RestClientException
      Since:
      4.3.5
      See Also:
    • patchForObject

      @Nullable <T> T patchForObject(String url, @Nullable Object request, Class<T> responseType, Map<String,?> uriVariables) throws RestClientException
      Update a resource by PATCHing the given object to the URI template, and return the representation found in the response.

      URI Template variables are expanded using the given map.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      NOTE: The standard JDK HTTP library does not support HTTP PATCH. You need to use e.g. the Apache HttpComponents request factory.

      Parameters:
      url - the URL
      request - the object to be PATCHed (may be null)
      responseType - the type of the return value
      uriVariables - the variables to expand the template
      Returns:
      the converted object
      Throws:
      RestClientException
      Since:
      4.3.5
      See Also:
    • patchForObject

      @Nullable <T> T patchForObject(URI url, @Nullable Object request, Class<T> responseType) throws RestClientException
      Update a resource by PATCHing the given object to the URL, and return the representation found in the response.

      The request parameter can be a HttpEntity in order to add additional HTTP headers to the request.

      NOTE: The standard JDK HTTP library does not support HTTP PATCH. You need to use e.g. the Apache HttpComponents request factory.

      Parameters:
      url - the URL
      request - the object to be PATCHed (may be null)
      responseType - the type of the return value
      Returns:
      the converted object
      Throws:
      RestClientException
      Since:
      4.3.5
      See Also:
    • delete

      void delete(String url, Object... uriVariables) throws RestClientException
      Delete the resources at the specified URI.

      URI Template variables are expanded using the given URI variables, if any.

      Parameters:
      url - the URL
      uriVariables - the variables to expand in the template
      Throws:
      RestClientException
    • delete

      void delete(String url, Map<String,?> uriVariables) throws RestClientException
      Delete the resources at the specified URI.

      URI Template variables are expanded using the given map.

      Parameters:
      url - the URL
      uriVariables - the variables to expand the template
      Throws:
      RestClientException
    • delete

      void delete(URI url) throws RestClientException
      Delete the resources at the specified URL.
      Parameters:
      url - the URL
      Throws:
      RestClientException
    • optionsForAllow

      Set<HttpMethod> optionsForAllow(String url, Object... uriVariables) throws RestClientException
      Return the value of the Allow header for the given URI.

      URI Template variables are expanded using the given URI variables, if any.

      Parameters:
      url - the URL
      uriVariables - the variables to expand in the template
      Returns:
      the value of the Allow header
      Throws:
      RestClientException
    • optionsForAllow

      Set<HttpMethod> optionsForAllow(String url, Map<String,?> uriVariables) throws RestClientException
      Return the value of the Allow header for the given URI.

      URI Template variables are expanded using the given map.

      Parameters:
      url - the URL
      uriVariables - the variables to expand in the template
      Returns:
      the value of the Allow header
      Throws:
      RestClientException
    • optionsForAllow

      Set<HttpMethod> optionsForAllow(URI url) throws RestClientException
      Return the value of the Allow header for the given URL.
      Parameters:
      url - the URL
      Returns:
      the value of the Allow header
      Throws:
      RestClientException
    • exchange

      <T> ResponseEntity<T> exchange(String url, HttpMethod method, @Nullable HttpEntity<?> requestEntity, Class<T> responseType, Object... uriVariables) throws RestClientException
      Execute the HTTP method to the given URI template, writing the given request entity to the request, and return the response as ResponseEntity.

      URI Template variables are expanded using the given URI variables, if any.

      Parameters:
      url - the URL
      method - the HTTP method (GET, POST, etc)
      requestEntity - the entity (headers and/or body) to write to the request may be null)
      responseType - the type to convert the response to, or Void.class for no body
      uriVariables - the variables to expand in the template
      Returns:
      the response as entity
      Throws:
      RestClientException
      Since:
      3.0.2
    • exchange

      <T> ResponseEntity<T> exchange(String url, HttpMethod method, @Nullable HttpEntity<?> requestEntity, Class<T> responseType, Map<String,?> uriVariables) throws RestClientException
      Execute the HTTP method to the given URI template, writing the given request entity to the request, and return the response as ResponseEntity.

      URI Template variables are expanded using the given URI variables, if any.

      Parameters:
      url - the URL
      method - the HTTP method (GET, POST, etc)
      requestEntity - the entity (headers and/or body) to write to the request (may be null)
      responseType - the type to convert the response to, or Void.class for no body
      uriVariables - the variables to expand in the template
      Returns:
      the response as entity
      Throws:
      RestClientException
      Since:
      3.0.2
    • exchange

      <T> ResponseEntity<T> exchange(URI url, HttpMethod method, @Nullable HttpEntity<?> requestEntity, Class<T> responseType) throws RestClientException
      Execute the HTTP method to the given URI template, writing the given request entity to the request, and return the response as ResponseEntity.
      Parameters:
      url - the URL
      method - the HTTP method (GET, POST, etc)
      requestEntity - the entity (headers and/or body) to write to the request (may be null)
      responseType - the type to convert the response to, or Void.class for no body
      Returns:
      the response as entity
      Throws:
      RestClientException
      Since:
      3.0.2
    • exchange

      <T> ResponseEntity<T> exchange(String url, HttpMethod method, @Nullable HttpEntity<?> requestEntity, ParameterizedTypeReference<T> responseType, Object... uriVariables) throws RestClientException
      Execute the HTTP method to the given URI template, writing the given request entity to the request, and return the response as ResponseEntity. The given ParameterizedTypeReference is used to pass generic type information:
       ParameterizedTypeReference<List<MyBean>> myBean =
           new ParameterizedTypeReference<List<MyBean>>() {};
      
       ResponseEntity<List<MyBean>> response =
           template.exchange("https://example.com",HttpMethod.GET, null, myBean);
       
      Parameters:
      url - the URL
      method - the HTTP method (GET, POST, etc)
      requestEntity - the entity (headers and/or body) to write to the request (may be null)
      responseType - the type to convert the response to, or Void.class for no body
      uriVariables - the variables to expand in the template
      Returns:
      the response as entity
      Throws:
      RestClientException
      Since:
      3.2
    • exchange

      <T> ResponseEntity<T> exchange(String url, HttpMethod method, @Nullable HttpEntity<?> requestEntity, ParameterizedTypeReference<T> responseType, Map<String,?> uriVariables) throws RestClientException
      Execute the HTTP method to the given URI template, writing the given request entity to the request, and return the response as ResponseEntity. The given ParameterizedTypeReference is used to pass generic type information:
       ParameterizedTypeReference<List<MyBean>> myBean =
           new ParameterizedTypeReference<List<MyBean>>() {};
      
       ResponseEntity<List<MyBean>> response =
           template.exchange("https://example.com",HttpMethod.GET, null, myBean);
       
      Parameters:
      url - the URL
      method - the HTTP method (GET, POST, etc)
      requestEntity - the entity (headers and/or body) to write to the request (may be null)
      responseType - the type to convert the response to, or Void.class for no body
      uriVariables - the variables to expand in the template
      Returns:
      the response as entity
      Throws:
      RestClientException
      Since:
      3.2
    • exchange

      <T> ResponseEntity<T> exchange(URI url, HttpMethod method, @Nullable HttpEntity<?> requestEntity, ParameterizedTypeReference<T> responseType) throws RestClientException
      Execute the HTTP method to the given URI template, writing the given request entity to the request, and return the response as ResponseEntity. The given ParameterizedTypeReference is used to pass generic type information:
       ParameterizedTypeReference<List<MyBean>> myBean =
           new ParameterizedTypeReference<List<MyBean>>() {};
      
       ResponseEntity<List<MyBean>> response =
           template.exchange("https://example.com",HttpMethod.GET, null, myBean);
       
      Parameters:
      url - the URL
      method - the HTTP method (GET, POST, etc)
      requestEntity - the entity (headers and/or body) to write to the request (may be null)
      responseType - the type to convert the response to, or Void.class for no body
      Returns:
      the response as entity
      Throws:
      RestClientException
      Since:
      3.2
    • exchange

      <T> ResponseEntity<T> exchange(RequestEntity<?> requestEntity, Class<T> responseType) throws RestClientException
      Execute the request specified in the given RequestEntity and return the response as ResponseEntity. Typically used in combination with the static builder methods on RequestEntity, for instance:
       MyRequest body = ...
       RequestEntity request = RequestEntity
           .post(URI.create("https://example.com/foo"))
           .accept(MediaType.APPLICATION_JSON)
           .body(body);
       ResponseEntity<MyResponse> response = template.exchange(request, MyResponse.class);
       
      Parameters:
      requestEntity - the entity to write to the request
      responseType - the type to convert the response to, or Void.class for no body
      Returns:
      the response as entity
      Throws:
      RestClientException
      Since:
      4.1
    • exchange

      <T> ResponseEntity<T> exchange(RequestEntity<?> requestEntity, ParameterizedTypeReference<T> responseType) throws RestClientException
      Execute the request specified in the given RequestEntity and return the response as ResponseEntity. The given ParameterizedTypeReference is used to pass generic type information:
       MyRequest body = ...
       RequestEntity request = RequestEntity
           .post(URI.create("https://example.com/foo"))
           .accept(MediaType.APPLICATION_JSON)
           .body(body);
       ParameterizedTypeReference<List<MyResponse>> myBean =
           new ParameterizedTypeReference<List<MyResponse>>() {};
       ResponseEntity<List<MyResponse>> response = template.exchange(request, myBean);
       
      Parameters:
      requestEntity - the entity to write to the request
      responseType - the type to convert the response to, or Void.class for no body
      Returns:
      the response as entity
      Throws:
      RestClientException
      Since:
      4.1
    • execute

      @Nullable <T> T execute(String uriTemplate, HttpMethod method, @Nullable RequestCallback requestCallback, @Nullable ResponseExtractor<T> responseExtractor, Object... uriVariables) throws RestClientException
      Execute the HTTP method to the given URI template, preparing the request with the RequestCallback, and reading the response with a ResponseExtractor.

      URI Template variables are expanded using the given URI variables, if any.

      Parameters:
      uriTemplate - the URI template
      method - the HTTP method (GET, POST, etc)
      requestCallback - object that prepares the request
      responseExtractor - object that extracts the return value from the response
      uriVariables - the variables to expand in the template
      Returns:
      an arbitrary object, as returned by the ResponseExtractor
      Throws:
      RestClientException
    • execute

      @Nullable <T> T execute(String uriTemplate, HttpMethod method, @Nullable RequestCallback requestCallback, @Nullable ResponseExtractor<T> responseExtractor, Map<String,?> uriVariables) throws RestClientException
      Execute the HTTP method to the given URI template, preparing the request with the RequestCallback, and reading the response with a ResponseExtractor.

      URI Template variables are expanded using the given URI variables map.

      Parameters:
      uriTemplate - the URI template
      method - the HTTP method (GET, POST, etc)
      requestCallback - object that prepares the request
      responseExtractor - object that extracts the return value from the response
      uriVariables - the variables to expand in the template
      Returns:
      an arbitrary object, as returned by the ResponseExtractor
      Throws:
      RestClientException
    • execute

      @Nullable <T> T execute(URI url, HttpMethod method, @Nullable RequestCallback requestCallback, @Nullable ResponseExtractor<T> responseExtractor) throws RestClientException
      Execute the HTTP method to the given URL, preparing the request with the RequestCallback, and reading the response with a ResponseExtractor.
      Parameters:
      url - the URL
      method - the HTTP method (GET, POST, etc)
      requestCallback - object that prepares the request
      responseExtractor - object that extracts the return value from the response
      Returns:
      an arbitrary object, as returned by the ResponseExtractor
      Throws:
      RestClientException