Third-party API wrapper in Java: how to design

Question

Suppose, there's a site that provides an API, such as this:

• Users post questions, answers on that site
• You can make GET and POST calls
• There are two types of authentication: weak (only gives read rights) and strong (gives both read and write rights)
• Right now, I'd like to read users' questions and answers (only need weak access) and send them messages or post my own questions in the future (would need strong access)
• The site's API has actions both to do with users (eg send a message) and with site in general (see about, see most popular questions)

What I have right now looks like this:

public class Wrapper  {
   private AccessToken accessToken;

   public Wrapper(...)  {
     //does some stuff
     //gets access token:
     getAccessToken(...);
   }    

   public AccessToken getAccessToken(...)  {
      AccessToken result;
      //gets access token, given the auth info provided as arguments
      accessToken = result;

      return result; 
   }

   public ArrayList<Question> getQuestions(User user)  {
       //gets user's questions, using the accessToken field
       //set's a user's questions field to the result and returns the result
   }

   public ArrayList<Answer> getAnswers(User user)  {
       //same as previous
   }

   public boolean sendMessage(User user)  {
      //sends a message, if current accessToken is strong
   }
}

and User class:

class User  {
  private String username;

  private ArrayList<Question> questions;
  private ArrayList<Answer> answers;

  public User(String username) {this.username=username;}    

  //getters and setters
}

So, to use it you would use something like this:

public class Main  {
  public static void main(String[] args)  {
     Wrapper wrapper = new Wrapper(...);
     ArrayList<Question> questions = wrapper.getQuestions(new User("username"));
     wrapper.sendMessage(new User("username2"));
  }
}

I have issues with this.

First of all, class User feels superfluous, since all the functionality is inside the Wrapper class.

Second, I wonder if what my methods do is wright - from the design's perspective: in getAccessToken I both return AccessToken and set a Wrapper 's field accessToken to the result. Is this the right approach? Or should the method only return access token and then that result should be assigned to a class' field explicitly? Same goes for the getQuestions and getAnswers methods: they both get the ArrayList s, return them and assign a User 's field to the result - all inside the single method.

I would like for a User class to have some meaning. I thought of doing it something like that:

    Wrapper wrapper = new Wrapper(...);

    User user = new User("username");
    user.getQuestions(wrapper.getAccessToken());
    user.sendMessage(wrapper.getAccessToken());

So, the Wrapper class would only serve as a place to get an access token from, which doesn't feel right as well. I could place the access token functionality inside the User class and use it like this:

     User user = new User("username", ...);
     user.getQuestions();
     user.sendMessage();

The User 's constructor would take both username and auth data, would get access token and store it inside a user and then use it when getting questions/answers or sending messages. I could make the accessToken field inside User class static so that all users shared the same token.

However, there are actions the site API provides, that aren't obviously connected with users: for instance, getting the site's most popular questions. It feels right to use a generic Wrapper class for that purpose which contradicts with the previous approach.

I'm new to this and only know a couple design patterns. Perhaps, there are widespread patterns that are to be used for this type of problem? Any help/advice is appreciated.

Answer 1

There are a few alternatives that you can do to solve your problem, but there is likely not one that is better than all others. The solution you choose will depend on the trade-offs and how you want your system to operate. The following are two common solutions to this type of problem.

1. Have the Wrapper generate a User : Instead of generating a User object separate from the Wrapper , you can have the Wrapper generate the User object. This allows the Wrapper to embed the AccessToken within the User without any outside client knowing that a user has an AccessToken . For example, you can use the following Wrapper and User definitions:

    public class Wrapper { public Wrapper(...) { // ... does some stuff, but DOES NOT get an access token ... } private AccessToken getAccessToken(...) { AccessToken result; // ... gets access token, given the auth info provided as arguments ... return result; } public User findUser(String username, ...) { return new User(username, getAccessToken(...)); } } class User { private String username; private final AccessToken token; public User(String username, AccessToken token) { this.user = user; this.token = token; } // ... getters and setters ... }

   Note that getAccessToken is now private , as no other client needs to access this method. All of the methods of Wrapper continue to accept a User argument, but they now should obtain the access token by calling getToken on the User object, rather than using a stored AccessToken in Wrapper .

   Also note that the token field is final , since the access token associated with a User should not change over the life of a User object.

2. Embed the Wrapper in User : This technique is similar to (1), but it also embeds the Wrapper object in the User object. This allows the User class to act as a live object, which can be queried for questions and answers and can be used to send messages. Since all of the methods of Wrapper accept a User argument, this is a good sign that the methods should be moved to User . The following is a halfway point to refactor the Wrapper methods into User :

    public class Wrapper { public Wrapper(...) { // ... does some stuff, but DOES NOT get an access token ... } private AccessToken getAccessToken(...) { AccessToken result; // ... gets access token, given the auth info provided as arguments ... return result; } public User findUser(String username, ...) { return new User(username, getAccessToken(...)); } public ArrayList<Question> getQuestions(User user) { //gets user's questions, using the accessToken field //set's a user's questions field to the result and returns the result } public ArrayList<Answer> getAnswers(User user) { //same as previous } public boolean sendMessage(User user) { //sends a message, if current accessToken is strong } } class User { private String username; private final AccessToken token; private final Wrapper wrapper; public User(String username, AccessToken token, Wrapper wrapper) { this.user = user; this.token = token; this.wrapper = wrapper; } public List<Question> findQuestions() { return wrapper.getQuestions(this); } public ArrayList<Answer> findAnswers() { return wrapper.getAnswers(this); } public boolean sendMessage() { return wrapper.sendMessage(this); } // ... getters and setters ... }

   Using this technique, clients can now directly get questions and answers from a User object. Note that the findQuestions and findAnswers methods start with find . This tips off clients that this call may be a long call (as opposed to getQuestions or getAnswers , which would make a client assume that it is a simple getter and the method would return nearly-instantly). The fact that these methods execute a remote call should also be documented in the Java-docs for the methods. If the call takes a long time, the methods should return a Future (or a similar object) and be made asynchronously.

   If you want to go all-in on the refactor, you can move all of the implementation details from the Wrapper class to the User class:

    public class Wrapper { public Wrapper(...) { // ... does some stuff, but DOES NOT get an access token ... } private AccessToken getAccessToken(...) { AccessToken result; // ... gets access token, given the auth info provided as arguments ... return result; } public User findUser(String username, ...) { return new User(username, getAccessToken(...)); } } class User { private String username; private final AccessToken token; private final Wrapper wrapper; public User(String username, AccessToken token, Wrapper wrapper) { this.user = user; this.token = token; this.wrapper = wrapper; } public List<Question> findQuestions() { // ... find the questions remotely ... } public ArrayList<Answer> findAnswers() { // ... find the answers remotely ... } public boolean sendMessage() { // ... send message remotely ... } // ... getters and setters ... }

   This may not be the best approach, as it may be a better idea to keep the details of accessing the remote API abstracted in the Wrapper class. This is a judgment call that will depend on the nature of your specific application.

There are numerous other techniques that you can do, but the above two are common approaches to the problem you are trying to solve.