1

I am building a SDK that will simplify the use of my API.

The problem is if when I have to return property of type enum. For example, I use strings instead of int for displaying enum such as

{
  "type": "CAR"
}

instead of

{
"type": 1
}

Now, my question regarding SDK design/development is should I parse this "type" property as enum or as string? If I parse it as enum, I am always in a danger that if new enum value is added, this conversion will throw an error. If I tend to anticipate it, and catch that error, I am still ending up with either a caught exception or invalid enum value.

On the other hand if I return it as string this problem is gone, but I am expecting that client (client app) keeps track of all the enums and enum changes.

What would be an expected approach? or if there is another way to handle this, please suggest.

1
  • Of all the ways C# is a wonderful language, its version of ENUM is pretty annoying, to me at least. – Graham May 4 '20 at 14:49
3

If I parse it as enum, I am always in a danger that if new enum value is added, this conversion will throw an error.

An error being thrown when the code can't handle the current situation is desirable. Failing in silence is the source of bugs, it's not the solution.

What you're implying is that you can fix your engine by turning off the "check engine" light. It doesn't solve the problem, it hides it, and that's going to bite you in the long run.

I am building a SDK that will simplify the use of my API.

The SDK is presumably going to handle the connection to the API, but it's not going to alter the data that comes from the API, I would assume. If not, I highly suggest reconsidering what exactly you expect your SDK to do, and question why that same behavior isn't already being exposed by your API as well.

Ideally, your SDK simply returns the code-consumer-friendly equivalent of whatever your API is already returning. Therefore, the API and SDK should be reusing the same enum. This specifically prevents the API from having enum values that the SDK doesn't, or vice versa.

Personally, I let my API and SDK depend on the same contract (= separate project which contains the enums, DTOs, ...) and have them be published at the same time. This ensures that each new version of the API comes with its own version of the SDK, thus ensuring that they are in sync with one another. Any consumer who wishes to target a specific version of the API can simply find the SDK with the matching version number.

Now, my question regarding SDK design/development is should I parse this "type" property as enum or as string?

Why is your API exposing an enum to its consumers if you are now going to question whether your SDK should be exposing an enum to its consumers? That makes little sense. The SDK should mirror the API for its data contract. If the SDK shouldn't expose an enum, neither should the API.

  • Do your consumers care that this is an enum?
  • Are they expected to handle this enum or know the closed list of values that it contains?
  • Is this enum going to be used by the consumer to pass to the SDK/API?

If you answered "yes" to any of these, then you're probably going to want to expose the enum itself.

Whether you use an enum or a string depends on how you intend to handle it:

  • Integer values are easy to handle, but lower on the human-readability scale.
  • Strings are harder to handle but are more human-readable.

This is a decision you have to make: is the effort to parse strings worth having a more human-readable API?

If the SDK is the only intended consumer of the API, then you can just have the API return the integer value. If you wish for humans to be able to use your API directly (even if only developers who are debugging it), it may be worth converting the enum value to a string for readability's sake.

We can't make this decision for you. How you design your data contract is up to you. Use whatever makes the most sense for your use case. Whether you prioritize the SDK's concerns or the SDK consumer's concerns is at your discretion.

20
  • I appreciate your time to make such an elaborate answer, but you responded by adding more question that were really not addressing my concerns here. Basically the main focus of my question is the best way for SDK to handle future enum values. Of course SDK will catch the exception, but I dont think my SDK would have to throw an exception that would break client app just because type VAN is added. I tend to believe that is more natural that SDK returns VAN or CAR as string, and let client app handles these value according to client app needs. – John May 4 '20 at 14:11
  • In this case enums should be well documented, because as you mentioned there is no way for client to know what values to expect. – John May 4 '20 at 14:12
  • @John: If you've already decided how the SDK should return its data, then why post the question? The questions I asked in this answer are to urge to you properly analyze your needs so you can find the solution that fits instead of making a big picture guess. Either option is possible, but you haven't explored your use case deeply enough to know which option you should favor. And if you've already decided, as your first comment here concludes with, then the question itself is moot. – Flater May 4 '20 at 14:15
  • @John: "I dont think my SDK would have to throw an exception that would break client app just because type VAN is added" It's better to fail than to return bad data and act like it's good (or to task your consumers with writing their own custom validation to cover for our SDK's known failures). You're right that it's better to not fail at all, and the enum going out of sync can be avoided as I've already addressed in the answer. My point in the first paragraph of the answer is that silent failures are not an improvement over loud failures if it's still the same thing failing. – Flater May 4 '20 at 14:16
  • Actually at this moment my SDK returns enums instead of strings and the problems behind it are terrible. Expecting a client to update SDK (lets say nuget package) because I have added additional value is beyond crazy. I am learning from my mistakes, and I find this approach very problematic. Of course, I dont want to run into a new approach that would have a new set of issues. I am just making a point that it is more natural for client to expect values, rather then SDK to enforce them. After all client app is using SDK, not other way arround. Furthermore, if I introduce a new enum value.... – John May 4 '20 at 14:35

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.