In a REST API I am working with, under certain circumstances (ex/ request originated in network) diagnostics data is returned with the response. Right now, a property is appended to the root object of the response with the diagnostic information (magically by the framework).
For Example:
{
"results" : [ ],
"timestamp" : 1427734909284
}
becomes:
{
"results" : [ ],
"timestamp" : 1427734909284,
"additionalinfo" : [POTENTIALLY A BUNCH OF JSON DATA THAT CAN INCLUDE TIMING,
DESCRIPTIONS OR RECOVERABLE ERRORS, AND CODE PATH INFO]
}
This never sat well with me, but right now I am attempting to build some documentation processing into this project, which makes this even more problematic.
Is this the RESTfully correct manner in which to return this data? Should it be a response header instead? Why/Why not?
There are two ways you can view your diagnostic information: part of an existing resource, or a separate resource. How you view it depends on your application requirements.
If the information is part of an existing resource, then you have the most “RESTful” representation possible. Note that REST does not strictly place requirements on the structure of your response objects. Use whatever is convenient. However, this approach may not be compatible with resource caching as your diagnostics may be stale with subsequent requests. If you don’t want to cache resources while collecting diagnostics, then great.
If the information is its own resource, then refer to HATEOAS and include a link to the diagnostic resource in your response. This approach requires a way to persist diagnostics on the server. You should also use a REST-compliant JSON format such as HAL JSON if you’re concerned about “RESTful” responses.
Sending diagnostics in a response header should the last option to consider. You have to properly encode/decode the data according to the HTTP/1.1 specification. Also, HTTP/1.1 headers are not compressed so your responses will be larger and slower than they would be if the diagnostics were part of the body. There’s nothing inherently wrong with it, just more trade-offs to consider.