Package com.azure.core.http.rest

Class RequestOptions

  • public final class RequestOptions
extends Object
    This class contains the options to customize an HTTP request. RequestOptions can be used to configure the request headers, query params, the request body, or add a callback to modify all aspects of the HTTP request.

    An instance of fully configured RequestOptions can be passed to a service method that preconfigures known components of the request like URL, path params etc, further modifying both un-configured, or preconfigured components.

    To demonstrate how this class can be used to construct a request, let's use a Pet Store service as an example. The list of APIs available on this service are documented in the swagger definition.

    Creating an instance of RequestOptions

     RequestOptions options = new RequestOptions()
     .setBody(BinaryData.fromString("{\"name\":\"Fluffy\"}"))
     .addHeader("x-ms-pet-version", "2021-06-01");

    Configuring the request with JSON body and making a HTTP POST request

    To add a new pet to the pet store, an HTTP POST call should be made to the service with the details of the pet that is to be added. The details of the pet are included as the request body in JSON format. The JSON structure for the request is defined as follows: 
    
 {
   "id": 0,
   "category": {
     "id": 0,
     "name": "string"
   },
   "name": "doggie",
   "photoUrls": [
     "string"
   ],
   "tags": [
     {
       "id": 0,
       "name": "string"
     }
   ],
   "status": "available"
 }
    To create a concrete request, Json builder provided in javax package is used here for demonstration. However, any other Json building library can be used to achieve similar results. 
     JsonArray photoUrls = Json.createArrayBuilder()
     .add("https://imgur.com/pet1")
     .add("https://imgur.com/pet2")
     .build();

 JsonArray tags = Json.createArrayBuilder()
     .add(Json.createObjectBuilder()
         .add("id", 0)
         .add("name", "Labrador")
         .build())
     .add(Json.createObjectBuilder()
         .add("id", 1)
         .add("name", "2021")
         .build())
     .build();

 JsonObject requestBody = Json.createObjectBuilder()
     .add("id", 0)
     .add("name", "foo")
     .add("status", "available")
     .add("category", Json.createObjectBuilder().add("id", 0).add("name", "dog"))
     .add("photoUrls", photoUrls)
     .add("tags", tags)
     .build();

 String requestBodyStr = requestBody.toString();
    Now, this string representation of the JSON request can be set as body of RequestOptions 
     RequestOptions options = new RequestOptions()
     .addRequestCallback(request -> request
         // may already be set if request is created from a client
         .setUrl("https://petstore.example.com/pet")
         .setHttpMethod(HttpMethod.POST)
         .setBody(requestBodyStr)
         .setHeader("Content-Type", "application/json"));

    • Constructor Detail

      • RequestOptions

        public RequestOptions()

    • Method Detail

      • setHeader

        public RequestOptions setHeader​(String header,
                                String value)
        Sets or replaces a header to the HTTP request.
        Parameters:
        header - the header key
        value - the header value
        Returns:
        the modified RequestOptions object

      • addHeader

        public RequestOptions addHeader​(String header,
                                String value)
        Adds a header to the HTTP request.
        Parameters:
        header - the header key
        value - the header value
        Returns:
        the modified RequestOptions object

      • addQueryParam

        public RequestOptions addQueryParam​(String parameterName,
                                    String value)
        Adds a query parameter to the request URL. The parameter name and value will be URL encoded. To use an already encoded parameter name and value, call addQueryParam("name", "value", true).
        Parameters:
        parameterName - the name of the query parameter
        value - the value of the query parameter
        Returns:
        the modified RequestOptions object

      • addQueryParam

        public RequestOptions addQueryParam​(String parameterName,
                                    String value,
                                    boolean encoded)
        Adds a query parameter to the request URL, specifying whether the parameter is already encoded. A value true for this argument indicates that value of QueryParam.value() is already encoded hence engine should not encode it, by default value will be encoded.
        Parameters:
        parameterName - the name of the query parameter
        value - the value of the query parameter
        encoded - whether this query parameter is already encoded
        Returns:
        the modified RequestOptions object

      • addRequestCallback

        public RequestOptions addRequestCallback​(Consumer<HttpRequest> requestCallback)
        Adds a custom request callback to modify the HTTP request before it's sent by the HttpClient. The modifications made on a RequestOptions object is applied in order on the request.
        Parameters:
        requestCallback - the request callback
        Returns:
        the modified RequestOptions object

      • setBody

        public RequestOptions setBody​(BinaryData requestBody)
        Sets the body to send as part of the HTTP request.
        Parameters:
        requestBody - the request body data
        Returns:
        the modified RequestOptions object

      • setThrowOnError

        public RequestOptions setThrowOnError​(boolean throwOnError)
        Sets whether exception is thrown when an HTTP response with a status code indicating an error (400 or above) is received. By default, an exception will be thrown when an error response is received.
        Parameters:
        throwOnError - true if to throw on status codes of 400 or above, false if not. Default is true.
        Returns:
        the modified RequestOptions object