title: How to pass parameters for REST request to Java method?
body: <p>We are building a Java SDK to simplify the access to one of our services that provide a REST API. This SDK is to be used by 3rd-party developers. </p>
  
  <p>One of the problems has been to find a good way to represent the optional parameters of each request.</p>
  
  <p>Let's say we have the rest endpoint: <code>GET /photos</code>
  which has several optional parameters: <code>sortBy</code>, <code>pageSize</code>, <code>pageNumber</code>, etc.</p>
  
  <p>One solution would be to accept a <code>Map&lt;String,String&gt;</code> as a parameter to the api method that represents that rest call. </p>
  
  <pre><code>interface RestService {   
      public List&lt;Photo&gt; getPhotos(Map&lt;String,String&gt; parameters);
  }
  </code></pre>
  
  <p>There are a couple of problems with this solution:</p>
  
  <ul>
  <li>The method's signature gives the developer no information about the names of optional parameters available to this method (as well as the valid values). He would need to consult the REST api documentation, and ideally we would like to avoid the need to.</li>
  <li>The developer will end up creating several Map's with the parameters for the methods he will call, hard coding the names and values of the parameters everywhere. This means that if they ever change, it will be an hassle to fix them.</li>
  </ul>
  
  <p>Another solution would be to use an Options object that would contain information about the optional parameters. We could even use the builder pattern to build this object. </p>
  
  <p>This is how the method signature would look like:</p>
  
  <pre><code>interface RestService {   
      public List&lt;Photo&gt; getPhotos(PhotosOptions options);
  }
  </code></pre>
  
  <p>The developer now knows what are the available optional parameters and can easily build a <code>PhotosOptions</code> like this:</p>
  
  <pre><code>PhotosOptions options = PhotosOptions.builder().sortBy(DESC).pageSize(200).build();
  List&lt;Photo&gt; photos = getPhotos(options);
  </code></pre>
  
  <p><strong>The problem is that the service we are trying to cover with the SDK has a huge range of requests that we need to implement and pretty much all of them have a different list of options that they allow. This may result in a large number of Options classes.</strong></p>
  
  <p><strong>What is the best solution here? Build an Options object (and its builder) for each combination?</strong> Inheritance doesn't quite help here because I have all sorts of combinations of parameters.</p>