REST API status as integer or as string?
My colleague and I are working on a REST API. We argued quite a bit about whether the resource / item status should be a string or an integer . We both need to read, understand and modify this resource (using separate applications). Since this is a very general question, google did not help resolve this argument. I wonder what is your experience and which path is better.
For example, let's say we have a Job resource accessible through the URI http://example.com/api/jobs/someid and it has the following JSON representation stored in a NoSQL database:
JOB A:
{
"id": "someid",
"name": "somename",
"status": "finished" // or "created", "failed", "compile_error"
}
So my question is - maybe it should be more like the 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 determine the status in our application logic. But I lean towards the first myself as it is much more readable ... You can also easily mix '0' (string) and 0 (number).
However, since the API is consumed by machines, readability is not that important. The use of numbers also has a number of other advantages - it is widely used when working with applications in the console and can be useful if you want to enable arbitrary new fail statuses, for example:
- status == 50 - means you have a problem with network component X,
- statuses> 100 - means several separate cases.
Once you have numbers, you don't have to compose all those line names for them. So which path is best in your opinion? Maybe we need multiple fields (this might muddy a bit):
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"
}
source to share
Personally, I would look at handling this situation with a combination of both approaches you mentioned. I would store statuses as integers in the database, but 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.
}
Then you can convert the numeric status stored in the database to an instance of this enumeration and use it to make decisions 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 are pedantic, you can also store these mappings in your database.
For API access you can go anyway depending on your requirements. You can even return the result with both a status number and status text:
object YourObject
{
status_code = 0,
status = "Failed"
}
You can also create an API to get the status name from code. However, returning the status code and name to the API will be better from a performance standpoint.
source to share