search

JornWildt / Mason

Documentation and examples for the Mason media type
MIT License
114 stars 6 forks source link

Discussion: adding @messages element to @meta #6

Open JornWildt opened 10 years ago

JornWildt commented 10 years ago

It could be nice to have some formal way for the server to inform clients about changes to the API. Right now it is possible to write such information as @meta.@description - but no one should/would be looking at that in a deployed up-and-running system.

Suggestion:

"@meta": 
{
  "@messages":
  [
    {
      "id": "hwer87932hj",
      "message": "This resource is deprecated. Clients should move on to ...",
      "@links": { ... links to relevant resources ...}
    }.
    {
      ...
    }
  ]
}

I was thinking about a "level" property for "warning", "debug" or "fatal" - but I don't think it makes sense: "Debug" - what should the client do here? "Fatal" - use some 4xx status code instead.

JornWildt commented 10 years ago

If message are to be handled "in production" then it should not be part of the @meta element since this can be removed at runtime by request of the client.