4

What are a few ways constants and enums are dealt with when creating an API Client? I'm writing a client in python for our API and I've hit a sticking point with this. We use a lot of mappings to numbers (to save space) and I was wondering what the best technique is. I can hard code them into the client, but if a new enum/constant gets added, the consumer would have to update his version of the client. I also thought about grabbing the maps/enums when the client is first initialized and cached until there is an update. Are these typical approaches, or is there a more effective way to do this?

Edit: This is a REST API but I'm making a python client (so platform specific I suppose) for it to make it easier to work with. For a little more detail, when I say enums, I just mean using a constant (like an integer) to represent a certain choice a consumer has for a certain attribute. So lets say someone using the API is saving what type of video game system they have. 1 = xbox, 2 = playstation, 3= wii, etc... Do I hardcode those into the python client for the consumer to use? Do I grab them from the server when the client is initialized and then cache them client side?

Improve this question
2
  • 1
    You don't specify what kind of an API this is. There's a pretty big difference between SOAP, HTTP/REST, RPC, or a platform-specific API (e.g. Java/Python/.NET client). Also not every client of an API is necessarily going to understand an "enum" or have the same definition of it.
    – Aaronaught
    Commented Jan 28, 2014 at 2:45
  • Also, what "space" are you trying to "save"? Don't leak database or other technical constraints to clients if you can avoid it.
    – Aaronaught
    Commented Jan 28, 2014 at 2:47

1 Answer 1

Reset to default
4

I cannot think of any reason to require numeric values in a REST API. Use strings, and in your specification, identify what the valid values are.

If you want to go the extra mile and write enums (or equivalent) for a platform-specific client then go for it, but you will of course have to maintain it. If at all possible, you should make these API clients part of the same build process, or set your build system to automatically build the API clients whenever you do a release build. That way, a new version of the client is automatically available whenever you publicly release a new version of the API.

I realize this isn't necessarily easy to do, but such is the nature of maintaining platform-specific clients. That's why most maintainers don't do it. Oracle may need to do it but you probably don't. Twitter, GitHub, PayPal, etc. - they don't maintain "clients", just the API and its specs/documentation. Sometimes there will be open-source clients maintained by completely separate teams, but the owners of the service itself take no responsibility for them.

Typically an API client that is completely customized for a particular platform could more accurately be called an SDK. Treat it with that level of care and respect and the rest of the pieces should fall into place. Are you really prepared to maintain an SDK?

Improve this answer
2
  • thanks for the advice. I've made some changes so we will use strings and show all of the valid values in our spec. As for the client, it's actually helped me in my testing and will likely only be used internally although I do think what you've said is spot on. Do you even advise against it for internal use? It makes a lot of operations very convenient/simple.
    – tonyl7126
    Commented Jan 29, 2014 at 2:06
  • I might ask why you're bothering with a REST API if it's only going to be used internally. Regardless... in what way do integers in the API make operations simpler than strings? They all get converted into enums anyway.
    – Aaronaught
    Commented Jan 29, 2014 at 3:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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