Rest – Is it a good practice to have a special value “ALL” in an enum

apienumjsonrest

I'm developing a new service in a micro-services environment.
This is a REST service.
For simplicity, let's say that the path is:
/historyBooks

And the POST method for this path creates a new history book.

Let's assume that a history book covers one or more eras in history.

For brevity, let's assume we have only the following eras of human history:

Ancient
Post Classical
Modern

In my code, I'd like to represent them in an enum.

The method's body (the payload) is in JSON format, and should include a field name eras. This field is a list of era values, that this book covers.

The body may look like:

{
  "name": "From the cave to Einstein - a brief history review",
  "author": "Foo Bar",
  "eras": ["Ancient", "Post Classical", "Modern"]
}

In this specific service, the business logic is:
If no eras provided in the input, then this book is considered to cover all eras.

In the API review, a suggestion was made:
Include another value, ALL, for the eras enum, to explicitly indicate that all of the eras are covered.

I think it has some pros and cons.

Pros:

Explicit input

Cons:

If two items in the list are provided, say ALL and Ancient – what will be taken from the application? I guess that ALL should override the other values, but that's new business logic.

If I run a query, for books that cover specific era(s), how would I represent a books that cover all eras? If ALL is also used for the output (using the same logic), then it's the consumer's responsibility to interpret ALL as ["Ancient", "Post Classical", "Modern"].

My Question

I think that having the new ALL causes more confusion than not having it at all.

What do you think? Would you add this ALL value or keep your API without it?

Best Answer

Depends on whether your available eras are available to the calling application. Presumably they are so the user can select what they're interested in. If that's the case then it's a front-end issue to supply an "ALL" option. If it were me, that would have it send a list of all eras rather than an "all" option. If not, then you need an "ALL" option and run the risk then that the front end will get things back from an era it won't understand.

As you point out, ALL with other options means you can get conflicting requests. One further consideration is that you can pass "ALL" then any other enums become exclusions rather than inclusions, e.g. "ALL", "Ancient" means "Everything except the Ancients". That makes some kind of sense but obviously the UI then has to reflect that which may just be over complex.

TL;DR; Mostly "ALL" is a UI nicety & you can achieve the same thing at the service level with no ambiguity so don't do it.

Related Solutions

Rest – Creating an entity relationship in REST: May I create the parent by posting to a child id

It sounds like you're suggesting that, whenever a user first posts to a non-existent relation, you will create it as part of the post.

If you're asking whether this kind of create-on-access pattern is a valid, acceptable development pattern, the answer is yes it is - it's both valid, and a fairly common pattern to see.

Java – Best approach for multilingual Java Enum

I would approach this problem as I would approach any localization issue: ResourceBundle. I use a class called I18n that has a static method called getMessage that takes a key and optionally a list of arguments. The key gets looked up in a ResourceBundle configured to use the default Locale or whatever you prefer (specifics here aren't important, so long as the caller to I18n doesn't have to know about what the Locale is).

The I18n class is as follows:

public final class I18n {
    private I18n() {
    }

    private static ResourceBundle bundle;

    public static String getMessage(String key) {
        if(bundle == null) {
            bundle = ResourceBundle.getBundle("path.to.i18n.messages");
        }
        return bundle.getString(key);
    }

    public static String getMessage(String key, Object ... arguments) {
        return MessageFormat.format(getMessage(key), arguments);
    }
}

In your project, you would have in package path.to.i18n, files containing messages.properties (default), messages_en.properties (Locale en), messages_it.properties (Locale it), etc.

When you need to translate an enum value, you shouldn't have to treat it any differently than any other key, except the key is the enum term.

In other words, you have:

public enum AccountStatusEnum {
  Active,
  Inactive,
  Pending
}

When you call I18n.getMessage, you pass with AccountStatusEnum.Active.toString() and the translation will be found in a property file with key "Active". If you're like me, and you prefer to use lower-case keys, then you should perform toLowerCase() on the string. Better still, you create a new I18n.getMessage that takes an Enum rather than a key, and that method calls the String version of I18n.getMessage with the enum value converted to string and in lowercase.

So you'd then add this to the I18n class:

    public static String getMessage(Enum<?> enumVal) {
        return getMessage(enumVal.toString().toLowerCase());
    }

I prefer to use this method because it incorporates the same translation logic in the same part of the program without impacting your design. You may even want to differentiate enum keys from your other keys, in which case you can begin each enum key with "enum.", so you would prepend "enum." when calling getMessage. Just remember to name your keys in your properties files accordingly.

I hope that helps!

My Question

Best Answer

Related Solutions

Rest – Creating an entity relationship in REST: May I create the parent by posting to a child id

Java – Best approach for multilingual Java Enum

Related Topic