REST API status as integer or as string?

Question

Me and my colleague are working on REST API. We've been arguing quite a lot whether status of a resource/item should be a string or an integer---we both need to read, understand and modify this resource (using separate applications). As this is a very general subject, google did not help to settle this argument. I wonder what is your experience and which way is better.

For example, let's say we have Job resource, which is accesible through URI http://example.com/api/jobs/someid and it has the following JSON representation which is stored in NoSQL DB:

JOB A:
{
   "id": "someid",
   "name": "somename",
   "status": "finished"  // or "created", "failed", "compile_error"
}

So my question is - maybe it should be more like following?

JOB B:
{
   "id": "someid",
   "name": "somename",
   "status": 0  // or 1, 2, 3, ...
}

In both cases each of us would have to create a map, that we use to make sense of status in our application logic. But I myself am leaning towards first one, as it is far more readable... You can also easily mix up '0' (string) and 0 (number).

However, as the API is consumed by machines, readability is not that important. Using numbers also has some other advantages - it is widely accepted when working with applications in console and can be beneficial when you want to include arbitrary new failed statuses, say:

• status == 50 - means you have problem with network component X,
• status > 100 - means some multiple special cases.

When you have numbers, you don't need to make up all those string names for them. So which way is best in you opinion? Maybe we need multiple fields (this could make matters a bit confusing):

JOB C:
{
   "id": "someid",
   "name": "somename",
   "status": 0, // or 1, 2, 3...
   "error_type": "compile_error",
   "error_message": "You coding skill has failed. Please go away"
}

Answer 1

Personally I would look at handling this situation with a combination of both approaches you have mentioned. I would store the statuses as integers within a database, but would create an enumeration or class of constants to map status names to numeric status values.

For example (in C#):

public enum StatusType
{
    Created = 0,
    Failed = 1,
    Compile_Error = 2,

    // Add any further statuses here.
}

You could then convert the numeric status stored in the database to an instance of this enumeration, and use this for decision making throughout your code.

For example (in C#):

StatusType status = (StatusType) storedStatus;

if(status == StatusType.Created)
{
    // Status is created.
}
else
{
   // Handle any other statuses here.
}

If you're being pedantic, you could also store these mappings in your DB.

For access via an API, you could go either way depending on your requirements. You could even return a result with both the status number and status text:

object YourObject
{
    status_code = 0,
    status = "Failed"
}

You could also create an API to retrieve the status name from a code. However returning both the status code and name in the API would be the best from a performance standpoint.