20

Recently I have been developing my own API and with that invested interest in API design I have been keenly interested how I can improve my API design.

One aspect that has come up a couple times is (not by users of my API but in my observing discussion about the topic): one should know just by looking at the code calling the API what it is doing.

For example see this discussion on GitHub for the discourse repo, it goes something like:

foo.update_pinned(true, true);

Just by looking at the code (without knowing the parameter names, documentation etc.) one cannot guess what it is going to do - what does the 2nd argument mean? The suggested improvement is to have something like:

foo.pin()
foo.unpin()
foo.pin_globally()

And that clears things up (the 2nd arg was whether to pin foo globally, I am guessing), and I agree in this case the later would certainly be an improvement.

However I believe there can be instances where methods to set different but logically related state would be better exposed as one method call rather than separate ones, even though you would not know what it is doing just by looking at the code. (So you would have to resort to looking at the parameter names and documentation to find out - which personally I would always do no matter what if I am unfamiliar with an API).

For example I expose one method SetVisibility(bool, string, bool) on a FalconPeer and I acknowledge just looking at the line:

falconPeer.SetVisibility(true, "aerw3", true);

You would have no idea what it is doing. It is setting 3 different values that control the "visibility" of the falconPeer in the logical sense: accept join requests, only with password and reply to discovery requests. Splitting this out into 3 method calls could lead to a user of the API to set one aspect of "visibility" forgetting to set others that I force them to think about by only exposing the one method to set all aspects of "visibility". Furthermore when the user wants to change one aspect they almost always will want to change another aspect and can now do so in one call.

  • 13
    This is precisely the reason why some languages have named parameters (sometimes even enforced named parameters). For example you could group a lot of settings in a simple update method: foo.update(pinned=true, globally=true). Or: foo.update_pinned(true, globally=true). So, the answer to your question should take also the language features into account, because a good API for language X might not be good for language Y and viceversa. – Bakuriu Jun 3 '14 at 8:43
  • Agreed - let's stop using booleans :) – Ven Jun 3 '14 at 11:06
  • 2
    It's known as "boolean trap" – user11153 Jun 3 '14 at 11:56
  • @Bakuriu Even C has enums, even if they're integers in disguise. I don't think there's any real world language where booleans are good API design. – Doval Jun 3 '14 at 12:41
  • 1
    @Doval I don't get what you are trying to saying. I used booleans in that situation simply because the OP used them, but my point is completely unrelated to the value passed. For example: setSize(10, 20) isn't as readable as setSize(width=10, height=20) or random(distribution='gaussian', mean=0.5, deviation=1). In languages with enforced named parameters booleans can convey exactly the same amount of information as using enums/named constants, so they can be good in APIs. – Bakuriu Jun 3 '14 at 16:48
27

Your desire not to split it out into three method calls is completely understandable, but you do have other options besides boolean parameters.

You could use enums:

falconPeer.SetVisibility(JoinRequestOptions.Accept, "aerw3", DiscoveryRequestOptions.Reply);

Or even a flags enum (if your language supports it):

falconPeer.SetVisibility(VisibilityOptions.AcceptJoinRequests | VisibilityOptions.ReplyToDiscoveryRequests, "aerw3");

Or you could use a Parameter Object:

var options = new VisibilityOptions();
options.AcceptJoinRequests = true;
options.ReplyToDiscoveryRequest = true;
options.Password="aerw3";
falconPeer.SetVisibility(options);

The Parameter Object pattern gives you a few other advantages that you may find helpful. It makes it easy to pass around and serialize a set of parameters, and you can easily give unspecified parameters "default" values.

Or you could just use boolean parameters. Microsoft seems to do it all the time with the .NET Framework API, so you could just shrug and say "if it's good enough for them, it's good enough for me".

  • The Parameter Object pattern still has a problem the OP stated: "Splitting this out into 3 method calls could lead to a user of the API to set one aspect of "visibility" forgetting to set others". – Lode Jun 6 '14 at 20:28
  • True, but I do think it makes the situation better (if not perfect). If the user is forced to instantiate and pass in a VisibilityOptions object, it may (with any luck) remind them that there are other properties on the VisibilityOptions object that they might want to set. With the three method calls approach, all they've got to remind them are comments on the methods they're calling. – BenM Jun 9 '14 at 3:29
6

Obviously, there are always exceptions to the rule, but as you explained well by yourself, there are certain advantages in having a readable API. Boolean arguments are particularly bothersome, as 1) they do not reveal an intent and 2) they imply that you call a function, where you actually should have two, because different things are going to happen depending on the boolean flag.

The main question is rather: how much effort do you want to invest into making your API more readable? The more outwards-facing it is, the more effort can easily be justified. If it is an API that is used only by one other unit, then it's not that big of a deal. If you're talking about a REST API where you plan to let the whole world lose upon it, then you may as well invest some more effort into making it more understandable.

As for your example, there is a simple solution: Apparently, in your case visibility is not just a true or false thing. Instead, you have a whole set of things that you consider "visibility". One solution may be to introduce something like a Visibility class, which covers all these different kinds of visibility. If you further apply the Builder-pattern for creating these, you may end up with code like the following:

Visibility visibility = Visibility.builder()
  .acceptJoinRequests()
  .withPassword("aerw3")
  .replyToDiscoveryRequests()
  .build();
falconPeer.setVisibility(visibility);

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.