REST API Best practice ? return Empty object vs no object

Question

let's say i have an API that returns users wallet balance and List of wallet transactions which is going to expiry

response = {
   user_balance: 20
   expiring_credits : [
     {object 1 }
     {object 2}
   ]
}

in case if user dont have any expiring transactions we can format respose in 2 ways option 1

 response = {
   user_balance: 20
 }

option 2

  response = {
    user_balance: 20
    expiring_credits : []
  }

which is the ideal option or best practices? and why? looking for some expert insights. many thanks.

Answer 1

Your returned data should reflect the shape of the data being asked for. If they're asking for a user's information, and that includes a user balance as one-to-one and expiring credits as a one-to-many, you should include those relationships. If there is nothing to be included, specifically call it out with a null if it's a one to one to let the dev know "there is a lack of data here" and if it is a one to many, return an empty array, as there were no dependant records but there was a master record.

An example endpoint:

/user/[id]/credits
GET
id: the user's id
{
  user_balance: null | number, // o:o
  expiring_credits: credits[] // o:m
}

This way the data shape is always the same for the consuming developer and they would not have to worry about top-level keys no existing on the returned object. It'll always be there, and it will always be consistent with the type returned.

If it exists, it will be this type. If it would be an array, it will always be an array. This lets people code to the data shape, not to the possibility of the data shape.

Answer 2

It would be always a good practice to make json response structure intact so that client does not need to understand whether is the attribute is empty as attribute itself missed our due to some authorization or can it is because of no data is present

If attribute is present and not data is present array it will be give more clarity to calling user that removing attribute itself.

Answer 3

which is the ideal option or best practices?

REST doesn't care.

---

What you have here is a question about schema design, and specifically whether or not your expiring credits field should be optional or mandatory.

For instance, OpenApi uses optional parameters by default; your specification must explicitly "opt-in" to using required parameters (the "required" field is optional). This pattern holds for objects in your schema , just as it does for parameters in your URI (the "required" field is optional ).

The choice between optional vs mandatory can impact you later if you discover that you need to modify the schema, and want to do so in a way that doesn't break existing clients. The XML community explored this question back in the day, so you will want to look into their conclusions (and in particular policies like must-ignore and must-forward).

Answer 4

I can't think of any good reason to omit a field just because it's empty. You might be able to save a few bytes in the response, but that is a very weak argument.

On the other hand: omission is not the same as absence. API's can return partial responses :

Partial response allows you to give application developers just the information they need.

source: Web API Design: The Missing Link

With partial responses:

api.example.com/user/1234 returns all fields by default:

response = {
   user_balance: 20,
   expiring_credits : [
       {object 1 },
       {object 2}
   ]
}

api.example.com/user/1234?fields=user_balance only sends user_balance , omitting expiring credits even if expiring credits exist:

response = {
   user_balance: 20
}

Answer 5

The better practice is to send an empty array. The reason is when someone calls your API and expect expiring_credits field to be present in the response, if you did not send it because it is empty, they can assume that they sent a bad request because the empty array is a valid value.

Answer 6

Note : Anything that I'm saying here is based on my own experience on web application and api development.
In my experience, always sending a static structure to the front-end or every other apis or web applications or wherever is better than not sending them at all.
I mean if you are working on a project and you have to send your data to the next implemented department, you have to have a standard for your responses and that means that you promise if for example you send some data with 200 response code from /me/ url, you surely have to promise that you always send ["username", "email"] fields. (even when they are null or empty strings) This makes the other department(that can be anything) to always trust the responses from your api.

response = {
    user_balance: 20
    expiring_credits : []
  }

So this is better.

Answer 7

response = {
  user_balance: 20
  expiring_credits : []
}

Option 2 is the best practice because of the following reasons

1. You don't have to write extra code to handle the undefined situation. This will simply render an empty grid.
2. Less prone to bugs.
3. Now the consumer is confirmed that ok the API is providing the correct response. It's just that there are no expiring_credits as of now.
4. While using libraries like Typescript, you don't have to mention an optional field.