API Patterns and Practices – How to Represent Enum Types in a Public API

apienumpatterns-and-practices

I am working on a simple API that I want to use for my own client, and to open to the public in the future.
I have "Item" objects which can have different "types". The type is a C "typedef enum", for the moment I have :

typedef enum {
    ItemTypeBool,
    ItemTypeNumber,
    ItemTypeDate,
} ItemType;

(I may add some in the future)

I am wondering if I should rather transfer it as integers or as defined "strings". The JSON would be :

For integers :

{
  "name": "The name",
  "type": 0,
   ...
}

For strings :

{
  "name": "The name"
  "type": "boolean"
   ...
}

I'm wondering if there's a best practice for this. Keeping the integer would slightly simplify the code, and reduce the bandwidth, but strings would be easier for developers to remember. I remember I worked on a project, and I had to remember 1=image, 2=audio, 3=html,… which doesn't make any real sense.

So I'm asking you, if you know any other aspect I should consider.

Best Answer

Provide the strings. Numbers are meaningless. You don't use them in your own code, right (you're wrapping enum values around, that are basically strings) - why punish the user with having to use these numbers?

The only pro if you do expose the numbers - easier for you to parse these. But hey, who cares about you. Take care of the API clients.

If you provide the strings - easier for the clients; won't ever have to say things like "4 had been deprecated in favor of 17"; slightly harder parsing on your behalf, but that's fine.

Do not provide both: as a user, i'm left to wonder

which one do I use? Both? [on to reading docs]
why are there two ways to say the same thing? are they subtly different? [on to reading docs]
what if I specify both and there's a mismatch? will it complain? will one take precedence? which one? [on to reading docs]

As you can see, you're having me read a lot of docs for no reason.

Related Solutions

C++ – Using scoped enums for bit flags in C++

The simplest way is to provide the operator overloads yourself. I am thinking of creating a macro to expand the basic overloads per type.

#include <type_traits>

enum class SBJFrameDrag
{
    None = 0x00,
    Top = 0x01,
    Left = 0x02,
    Bottom = 0x04,
    Right = 0x08,
};

inline SBJFrameDrag operator | (SBJFrameDrag lhs, SBJFrameDrag rhs)
{
    using T = std::underlying_type_t <SBJFrameDrag>;
    return static_cast<SBJFrameDrag>(static_cast<T>(lhs) | static_cast<T>(rhs));
}
    
inline SBJFrameDrag& operator |= (SBJFrameDrag& lhs, SBJFrameDrag rhs)
{
    lhs = lhs | rhs;
    return lhs;
}

(Note that type_traits is a C++11 header and std::underlying_type_t is a C++14 feature.)

API Domain Model – Exposing Domain Models Over API

That's exactly one of the reasons why DTOs exists.

The tradeoff here is that adding DTOs makes your implementation a bit more complex, and thus prone to errors - such as a mismatch in mapping the domain object to a DTO. Use unit tests for this!

Another thing that you could do with your DTO and tends to be highly overlooked in RESTful services is treating hypertext data for references, nested objects and possible operations.

Refer to Martin Fowler's PoEAA: "[...] it's worth mentioning that another advantage is to encapsulate the serialization mechanism for transferring data over the wire. By encapsulating the serialization like this, the DTOs keep this logic out of the rest of the code and also provide a clear point to change serialization should you wish."

http://martinfowler.com/eaaCatalog/dataTransferObject.html

TL;DR: I like the idea of separating the concerns of domain logic and "RESTful wiring" through DTOS, albeit introducing a more complex design.

Best Answer

Related Solutions

C++ – Using scoped enums for bit flags in C++

API Domain Model – Exposing Domain Models Over API

Related Topic