REST design - Should I return descriptive data that can be implied or deduced

Question

I am looking for best practice principle here. As part of my REST Api, I am returning some basic info for a user. Lets say the user can be an "owner" of a company, in which case they have full access to every resource of the company. Or they could have been given delegated access to certain parts of the company. Now I have these two choices of json to return

if user is an owner ...

{
     companyId : "123",
     companyName: "Acme",
     isOwner: true,
     delegatedAuthority : null 
}

if user has delegated access to certain resources of the company ...

{
     companyId : "123",
     companyName: "Acme",
     isOwner: false,
     delegatedAuthority : 
        {
            // An object that provides all the details about the delegation.
        }
}

Obviously, from an implementation perspecitive, I would be doing something as simple as setting isOwner = delegatedAuthority == null behind the scenes.

But should I even returning the flag? From an exploratory or descriptive perspective, it seems like a nice thing to return. Could be helpful for someone building a consumer who might not be familiar with the API or the domain. But for someone familiar with the API/domain, it seems like I might be violating DRY and returning redundant information. Would they now feel compelled to write error checking code to make sure I don't lie to them and return both the isOwner = true and delegatedAuthority != null

What are the principles you would consider and weigh?

Answer 1

Is It always obvious? What if what determines isOwner changes behind the scenes?

There will be a ton of client code that will break, if the association between the two fields is gone.

Thinking about an interface, I would keep isOwner. If the underlying relation changes, your clients wont break.

Answer 2

It is wise to build your business logic in one place. In your case business logic is: if that data structure delegatedAuthority is missing, the person is owner.

You should encapsulate the logic in one method. It is up to you if you do it on server side or client side. If it is implemented on server side, return the boolean in REST call. You can also only return data structure, but then I suggest you implement the logic in client side. Eg you are not checking everywhere if delegatedAuthority != null but you have one piece of code that consumes the REST endpoint and provides isOwner() functionality for you.

On the other hand - you could also rebuild your API so that instead of isOwner you are returning role that may also contain other roles that are currently stored in delegatedAuthority. Eg return the same data structure for owners and other people. But again - this is not only a question of single endpoint, but rather a decision of where to build your business logic in general.