Rest (vault-java-driver 2.0.0 API)

java.lang.Object
- com.bettercloud.vault.rest.Rest

public class Rest
extends java.lang.Object

A simple client for issuing HTTP requests. Supports the HTTP verbs:

GET
POST
PUT
DELETE

Rest uses the Builder pattern to provide a basic DSL for usage. Methods for configuring an HTTP request (i.e. url(), parameter(), and header()) are designed to be chained together, while methods corresponding to the HTTP verbs are terminating operations:


 final RestResponse getResponse = new Rest()
                              .url("https://httpbin.org/get")
                              .header("header-1", "foo")
                              .header("header-2", "bar")
                              .parameter("param-1", "up")
                              .parameter("param-2", "down")
                              .get();

 final RestResponse postResponse = new Rest()
                              .url("https://httpbin.org/post")
                              .header("header-1", "foo")
                              .header("header-2", "bar")
                              .body( jsonString.getBytes("UTF-8") )
                              .post();

Header and parameter names and values are url-encoded by the Rest client prior to sending the request. The URL string should be url-encoded by you (if necessary) prior to passing it.

Constructor Summary

Constructors
Constructor and Description

Rest()

Constructors
Constructor and Description
`Rest()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Rest`	`body(byte[] body)` Sets a binary payload that will be sent as the request body for POST or PUT requests.
`Rest`	`connectTimeoutSeconds(java.lang.Integer connectTimeoutSeconds)` The number of seconds to wait before giving up on establishing an HTTP(S) connection.
`RestResponse`	`delete()` Executes an HTTP DELETE request with the settings already configured.
`RestResponse`	`get()` Executes an HTTP GET request with the settings already configured.
`Rest`	`header(java.lang.String name, java.lang.String value)` Adds a header to be send with the HTTP request.
`Rest`	`parameter(java.lang.String name, java.lang.String value)` Adds a parameter to be sent with the HTTP request.
`RestResponse`	`post()` Executes an HTTP POST request with the settings already configured.
`RestResponse`	`put()` Executes an HTTP PUT request with the settings already configured.
`Rest`	`readTimeoutSeconds(java.lang.Integer readTimeoutSeconds)` After an HTTP(S) connection has already been established, this is the number of seconds to wait for all data to finish downloading.
`Rest`	`sslPemUTF8(java.lang.String pemFileContents)` An X.509 certificate, to use when communicating with Vault over HTTPS.
`Rest`	`sslVerification(java.lang.Boolean sslVerification)` Whether or not HTTPS connections should verify that the server has a valid SSL certificate.
`Rest`	`url(java.lang.String urlString)` Sets the base URL to which the HTTP request will be sent.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Rest
```
public Rest()
```
- Method Detail
  - url
```
public Rest url(java.lang.String urlString)
```
    Sets the base URL to which the HTTP request will be sent. The URL may or may not include query parameters (e.g. http://httpbin.org/get?param-1=foo).
    
    Depending on which HTTP verb is ultimately used, than any additional parameters set via the parameters() method may be appending to this URL.
    
    Either way, the responsibility for any url-encoding of this base URL string belongs to the caller.
    
    Parameters:
    
    urlString - A URL string, with any necessary url-encoding already applied @return The Rest instance itself
    
    Returns:
    
    This object, with urlString populated, ready for other builder-pattern config methods or an HTTP verb method
  - body
```
public Rest body(byte[] body)
```
    Sets a binary payload that will be sent as the request body for POST or PUT requests. Any value set here will be ignored for GET requests. Conversely, if a value IS set here... then any additional parameter values set by parameter() will be ignored for POST or PUT requests.
    
    Parameters:
    
    body - The payload to send with a POST or PUT request (e.g. a JSON string)
    
    Returns:
    
    This object, with body populated, ready for other builder-pattern config methods or an HTTP verb method
  - parameter
```
public Rest parameter(java.lang.String name,
                      java.lang.String value)
               throws RestException
```
    Adds a parameter to be sent with the HTTP request. Depending on which HTTP verb is ultimately used, this parameter may either be appended to the URL or else posted with the request body. Either way, both the parameter name and value will be automatically url-encoded by the Rest client.
    
    For POST and PUT requests, these parameters will only be sent in the request body if that body is otherwise unset. In other words, if the body() method is invoked, then parameter() invocations will be ignored for a POST or PUT.
    
    This method may be chained together repeatedly, to pass multiple parameters with a request. When the request is ultimately sent, the parameters will be sorted by their names.
    
    Parameters:
    
    name - The raw parameter name (not url-encoded)
    
    value - The raw parameter value (not url-encoded)
    
    Returns:
    
    This object, with a parameter added, ready for other builder-pattern config methods or an HTTP verb method
    
    Throws:
    
    RestException - If any error occurs, or unexpected response received from Vault
  - header
```
public Rest header(java.lang.String name,
                   java.lang.String value)
            throws RestException
```
    Adds a header to be send with the HTTP request.
    
    Both the header name and value will be automatically url-encoded by the Rest client.
    
    This method may be chained together repeatedly, to pass multiple headers with a request. When the request is ultimately sent, the headers will be sorted by their names.
    
    Parameters:
    
    name - The raw header name (not url-encoded)
    
    value - The raw header value (not url-encoded)
    
    Returns:
    
    This object, with a header added, ready for other builder-pattern config methods or an HTTP verb method
    
    Throws:
    
    RestException - If any error occurs, or unexpected response received from Vault
  - connectTimeoutSeconds
```
public Rest connectTimeoutSeconds(java.lang.Integer connectTimeoutSeconds)
```
    The number of seconds to wait before giving up on establishing an HTTP(S) connection.
    
    Parameters:
    
    connectTimeoutSeconds - Number of seconds to wait for an HTTP(S) connection to successfully establish
    
    Returns:
    
    This object, with connectTimeoutSeconds populated, ready for other builder-pattern config methods or an HTTP verb method
  - readTimeoutSeconds
```
public Rest readTimeoutSeconds(java.lang.Integer readTimeoutSeconds)
```
    After an HTTP(S) connection has already been established, this is the number of seconds to wait for all data to finish downloading.
    
    Parameters:
    
    readTimeoutSeconds - Number of seconds to wait for all data to be retrieved from an established HTTP(S) connection
    
    Returns:
    
    This object, with readTimeoutSeconds populated, ready for other builder-pattern config methods or an HTTP verb method
  - sslVerification
```
public Rest sslVerification(java.lang.Boolean sslVerification)
```
    Whether or not HTTPS connections should verify that the server has a valid SSL certificate. Unless this is set to false, the default behavior is to always verify SSL certificates.
    
    SSL CERTIFICATE VERIFICATION SHOULD NOT BE DISABLED IN PRODUCTION! This feature is made available to facilitate development or testing environments, where you might be using a self-signed cert that will not pass verification. However, even if you are using a self-signed cert on your server, you can still leave SSL verification enabled and have your application supply the cert using sslPemFile(), sslPemResource(), or sslPemUTF8().
    
    Parameters:
    
    sslVerification - Whether or not to verify the SSL certificate used by the server with HTTPS connections. Default is true.
    
    Returns:
    
    This object, with sslVerification populated, ready for other builder-pattern config methods or an HTTP verb method
  - sslPemUTF8
```
public Rest sslPemUTF8(java.lang.String pemFileContents)
```
    An X.509 certificate, to use when communicating with Vault over HTTPS. This method accepts a string containing the certificate data. This string should meet the following requirements:
    - Contain an unencrypted X.509 certificate, in PEM format.
    - Use UTF-8 encoding.
    - Contain a line-break between the certificate header (e.g. "-----BEGIN CERTIFICATE-----") and the rest of the certificate content. It doesn't matter whether or not there are additional line breaks within the certificate content, or whether there is a line break before the certificate footer (e.g. "-----END CERTIFICATE-----"). But the Java standard library will fail to properly process the certificate without a break following the header (see http://www.doublecloud.org/2014/03/reading-x-509-certificate-in-java-how-to-handle-format-issue/).
    Parameters:
    
    pemFileContents - An X.509 certificate, in unencrypted PEM format with UTF-8 encoding.
    
    Returns:
    
    This object, with sslPemUTF8 populated, ready for other builder-pattern config methods or an HTTP verb method
  - get
```
public RestResponse get()
                 throws RestException
```
    Executes an HTTP GET request with the settings already configured. Parameters and headers are optional, but a RestException will be thrown if the caller has not first set a base URL with the url() method.
    
    If a body payload has been set through the body() method, then it will be ignored when sending a GET request.
    
    Returns:
    
    The result of the HTTP operation
    
    Throws:
    
    RestException - If an error occurs, or an unexpected response received
  - post
```
public RestResponse post()
                  throws RestException
```
    Executes an HTTP POST request with the settings already configured. Parameters and headers are optional, but a RestException will be thrown if the caller has not first set a base URL with the url() method.
    CGI parameters can always be passed via a query string on the URL. Also, parameter values set via the parameter() method will be sent with the POST request as form data. However, if a body payload is provided via the body() method, then that takes precedence over any parameters set via parameter(), and those values will be discarded.
    
    Returns:
    
    The result of the HTTP operation
    
    Throws:
    
    RestException - If an error occurs, or an unexpected response received
  - put
```
public RestResponse put()
                 throws RestException
```
    Executes an HTTP PUT request with the settings already configured. Parameters and headers are optional, but a RestException will be thrown if the caller has not first set a base URL with the url() method.
    CGI parameters can always be passed via a query string on the URL. Also, parameter values set via the parameter() method will be sent with the PUT request as form data. However, if a body payload is provided via the body() method, then that takes precedence over any parameters set via parameter(), and those values will be discarded.
    
    Returns:
    
    The result of the HTTP operation
    
    Throws:
    
    RestException - If an error occurs, or an unexpected response received
  - delete
```
public RestResponse delete()
                    throws RestException
```
    Executes an HTTP DELETE request with the settings already configured. Parameters and headers are optional, but a RestException will be thrown if the caller has not first set a base URL with the url() method. Note that any parameters are set in the query string. This method does not send a request body, as some HTTP servers will ignore it for DELETE requests.
    
    Returns:
    
    The result of the HTTP operation
    
    Throws:
    
    RestException - If an error occurs, or an unexpected response received

Class Rest

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Rest

Method Detail

url

body

parameter

header

connectTimeoutSeconds

readTimeoutSeconds

sslVerification

sslPemUTF8

get

post

put

delete