3

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.

One of the problems has been to find a good way to represent the optional parameters of each request.

Let's say we have the rest endpoint: GET /photos which has several optional parameters: sortBy, pageSize, pageNumber, etc.

One solution would be to accept a Map<String,String> as a parameter to the api method that represents that rest call. 

interface RestService {   
    public List<Photo> getPhotos(Map<String,String> parameters);
}

There are a couple of problems with this solution:

  • 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.
  • 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.

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.

This is how the method signature would look like:

interface RestService {   
    public List<Photo> getPhotos(PhotosOptions options);
}

The developer now knows what are the available optional parameters and can easily build a PhotosOptions like this:

PhotosOptions options = PhotosOptions.builder().sortBy(DESC).pageSize(200).build();
List<Photo> photos = getPhotos(options);

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.

What is the best solution here? Build an Options object (and its builder) for each combination? Inheritance doesn't quite help here because I have all sorts of combinations of parameters.

Mario Duarte
  • 3,145
  • 7
  • 27
  • 37
  • Don't now if this will be of any help to you. I wrote this https://github.com/spacifici/simple-rest-client, is a REST client library that permits to use REST services by writing their interface (literally a java interface). Feel free to use it. – spacifici Oct 11 '13 at 14:55

1 Answers1

0

The better way is use options object as you showed:

interface RestService {   
    public List<Photo> getPhotos(PhotosOptions options);
}

This is very difficult method and require to type a lot of letters, you will have a lot of classes and other ass-pain.

But my opinion is that this way is better then others because it provides a strong methods signature, makes your SDK more deterministic. If you separate your classes by packages correctly you will see that this is a better way.

Users will tell you thanks.

I had the same question some time ago, after several tries I selected this method and I am happy now.

Nicolai
  • 5,489
  • 1
  • 24
  • 31
  • I also believe that to be the best way. However, I am concerned about the excessive number of Options classes (and its builders) we will end up having to write and maintain. We are wondering if the benefits to the users of the sdk compensate the extra work and complexity (by considerably increasing the number of classes). – Mario Duarte Oct 11 '13 at 22:33