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?
2
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?
2