Returning different JSON results for the same request - is this a violation of REST?

Question

Note the following from Roy Fielding concerning REST design, guidelines & principals.

5.2.1.1 Resources and Resource Identifiers

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource.

A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.

More precisely, a resource R is a temporally varying membership function MR(t), which for time t maps to a set of entities, or values, which are equivalent. The values in the set may be resource representations and/or resource identifiers. A resource can map to the empty set, which allows references to be made to a concept before any realization of that concept exists -- a notion that was foreign to most hypertext systems prior to the Web [61]. Some resources are static in the sense that, when examined at any time after their creation, they always correspond to the same value set. Others have a high degree of variance in their value over time.

The only thing that is required to be static for a resource is the semantics of the mapping, since the semantics is what distinguishes one resource from another.

The key points have been bolded, the rest of the paragraph I have included is for context.

Here is the scenario.

I have a web api that has a endpoint: http://www.myfakeapi.com/people

When a client does a GET request to this endpoint, they receive back a list of people.

Person
{
  "Name": "John Doe",
  "Age": "23",
  "Favorite Color": "Green"
}

Ok, well that's cool.

But is it against REST design practices and principles if I have a 'Person' who does not have a Favorite Color and I want to return them like this:

Person
{
  "Name": "Bob Doe",
  "Age": "23",
}

Or should I return them like this:

Person
{
  "Name": "Bob Doe",
  "Age": "23",
  "Favorite Color": null
}

The issue is that the client requesting the resource has to do extra work to see if the property even exist in the first place. Some 'Person's' have favorite colors and some don't. Is it against REST principals to just omit the json property of 'Favorite Color' if they don't exist - or should that property be given a 'null' or blank value?

What does REST say about this? I am thinking that I should give back a null and not change the representation of the resource the client is requesting by omitting properties.

Answer 1

There are various ways we can deal with this, depends upon the use case, I'll list them only by one

1) Prefer enums (only if it makes sense to your use case)

{
  "Name": "Bob Doe",
  "Age": "23",
  "Favorite Color": NO_COLOR
}

When you know the values for your property at the beginning, define a set of enum constants, and assign a default value if the property does not apply to the user. This helps in a few ways:

• Your client knows what are the possible values so they can prepare their client system accordingly.

• By giving default enum constant, we convey that value of the particular field is successfully retrieved from either persistent storage or maybe from another remote service, but it has default value because the property may not apply to the user OR user doesn't have any value for this property.

• By avoiding NULL pattern, your client code will be resilient and the client can prepare their code for default enum constant.

• When you start to serve more users, you may need to add a few more enum constants which may not apply to every client of yours. When you add new enums which they don't know, they can easily handle this in their parsing libraries and convert into something as per client application design. In Jackson, we can use DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_AS_NULL for this.

2) Use Null - Do not create enum constants for everything

There are cases perfectly valid to have a NULL object. For instance, in the below example, it makes sense to use null if there is no favourite quote.

{
  "Name": "Bob Doe",
  "Age": "23",
  "Favorite Quote": null
}

3) Document your required properties clearly

If you use swagger for your rest API documentation, you can mark mandatory properties as required. The ones not marked are optional. In that way, the client will be prepared to handle if they are NULL or empty string. (It should apply to other API documentation tools as well)

Bad practice: I notice a few users code in such a way, they send errors in the same response model they send their success response 200. Refer this question & answer. This is definitely a bad practice. Don't mix two different responses and mark one property as optional - use status codes to convey any problems. I'm not talking about partial response here.

4) Add/Modify properties (as long as you're not breaking a contract with the client)

Say the Favorite Color property is added later and currently you're sending the following response to your client. You will publish your new contract to your clients when you add Favorite Color, but your clients should have fail-safe code and they should handle the unknown properties. In Jackson, we will use DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES for this. Non-breaking changes do not necessarily require v2.

Person
{
  "Name": "Bob Doe",
  "Age": "23",
}

So, answer to your question is, you should start looking at the first three options while you design your rest API, you don't require to omit any properties. But, you may be required to add a few properties later(covered at #4), which is perfectly fine.

Answer 2

Off the top of my head I can't think of any REST constraints that this violates (here's a link to a brief overview if you're interested). It also doesn't violate idempotency for a GET request. However, it is still bad practice.

The consumer of your API should know what to expect and ideally this should be well documented (I like using Swagger a lot for this). Any changes in what to expect should be communicated to consumers, possibly in the form of release notes. Changes that could potentially be breaking for your consumer should be delivered in a new version of your API.

Since your Person1 and Person2 are technically different object structures, that could be breaking in itself (let's face it, we don't always find the edge cases as devs). You don't just want your API to work on a basic level and to hell with the end users - you want to design it with the end-consumer in mind so that their lives are made easier.