Doubt on JSON structure - Terrifically Simple JSON

[pranavchaudhary]

Hi,

In my situation, I am an Enterprise CTO and my 3rd party service provider's JSON API doesn't adhere to Apigee's Best Practices found here:-

1. Apigee's book "Web API: The Missing Link" which gives some guidance and best practices around JSON usage (among other things).

2. @Martin Nally @Martin Nally Martin Nally's https://github.com/mpnally/Terrifically-Simple-JSON

Specifically, I was wondering if I could have your thoughts on the following:-

If an application developer were to make an API call like

GET /Products

and the request payload needed to include say 1 attributes which is

State

I would argue that the cleanest/better JSON structure would be

{

	"State": "New York"

}

as opposed to

{
	"productSegment": {

		"State" : "New York"

	}
}

My argument is that the JSON object itself corresponds to the product segment so there is no need to call it out again unnecessarily complicating the payload. Thoughts ?

I know this sounds like minutiae but it would be nice to have some clarity around how to structure JSON.

Side Question: Is it ok to have a request body in a GET call?

[pranavchaudhary]

@Dino-at-Google @Martin Nally @Chris Hood

[robert]

Hi @Pranav Chaudhary. First, GET's are not supposed to contain a message body. Use a query parameter for that, especially since you are sending a simple state=CA or something like that. This approach also lends itself well for response caching.

Yes, your first example is cleaner. The resource is "Products" so productSegment seems redundant. Again, I'm referring to the Response object as you should not use a body in a GET request.

[pranavchaudhary]

Can you elaborate further with response caching? What would the flow for that look like?

In reality, I actually have 10 attributes and I was under the impression that the revised HTTP spec has removed the clause that disallowed request body in a GET call. Can you point me to some material that says GETs are not supposed to contain a message body?

[robert]

10 attributes are fine as query parameters.

Take a look at the response caching policy here: https://docs.apigee.com/api-platform/reference/policies/response-cache-policy

I typically don't get into REST design debates with folks as people get religious about it. Many API developers feel it's bad practice to put a message body with a GET request and there are plenty of threads on the web containing those discussions. Just do a quick Google search about sending payloads with a GET request to read them. You can also read Roy Fielding's thoughts about it. Just because you can do something doesn't mean it's a good\best practice. Again, I'm not into debating about it but I'm sure plenty of other people here might be. 🙂