Feature Request: log

[arterrey]

Thankyou for this helpful spec. I would like to request an addition to the spec - an optional key "log" which would be a list of log data generated during any given transaction.

For example:

{
    status : "success",
    data : {
        "posts" : [
            { "id" : 1, "title" : "A blog post", "body" : "Some useful content" }
        ]
     },
    log: [
        "New post created",
        "Editor notified"
    ]
}

I don't think it is needed to specify what the type of itmes in the log key are. For example they could be dictionaries.

{
    status : "success",
    log: [
        {"level": "DEBUG", "message": "Workflow state changed to published"}
    ]
}

Motivation: Particularly in admin interfaces it is helpful to have more detail on actions taken. For example an application could detect that a user is a system admin and generate more information in the return objects.

[trondhuso]

Wouldn't that just be part of the data bucket?

[f1ncc]

Should the data in the "log" key be shown to the end user on the page or should it just be accessed by the browser console?

[arterrey]

@trondhuso
I think there are cases where you want to return debugging information that is not inline with application data. In a sense when a client application requests for data it is not asking for logs that were generated as pat of that request - but nevertheless logs are useful when you need them.

@sathya717 weather or not logs are accessible in the user interface or in the web console would be outside of the scope of a standard like this. It would certainly be accessible from inspecting the network tab in development tools.

[asiby]

IMHO, this is an application level requirement. One could wonder if the log is about a success or an error. That makes you think if you use log, then should the data at a deeper level mention something about the type of log? That type could be anything like debug, error, success, warning, notice, etc.

I think that a regular JSend success response could encapsulate a data that has a type attribute which can be log for instance. After that, the sky is the limit.

[arterrey]

@asiby I disagree, logs are generally not an application concern. If I want to query a service - the data that I'm expecting should not contain a log key with information about how the service produced the response. However, I can see that there are circumstances where you would want to turn on some extra debugging that, and it would be convenient if that debugging can be returned with a response out-of-line of the core payload so it doesn't effect the application.

[trondhuso]

Where I come from - the news production world - there are placeholders to tell when an article was first produced and when it was last updated. That is part of the data.
For instance in the News In JSON standard that IPTC has created the first version is marked up with the parameter: "firstcreated", then if there is an update of the news this is stated with "versioncreated".
So, this is not part of a possible envelope/wrapper in what I see the role of jsend.
Link to News in Json (ninjs) https://iptc.org/std/ninjs/ninjs-schema_1.3.json

Wouldn't you also perhaps require a separate log connection and response if you need such information? And then that debug-information would be part of the data-bucket...

Just some thoughts.