search

JornWildt / Mason

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

Discussion: should Mason include a "deprecated" attribute like in HAL #5

Closed JornWildt closed 10 years ago

JornWildt commented 10 years ago

Citing from the HAL spec:

5.4. deprecation

   The "deprecation" property is OPTIONAL.

   Its presence indicates that the link is to be deprecated (i.e.
   removed) at a future date.  Its value is a URL that SHOULD provide
   further information about the deprecation.

   A client SHOULD provide some notification (for example, by logging a
   warning message) whenever it traverses over a link that has this
   property.  The notification SHOULD include the deprecation property's
   value so that a client manitainer can easily find information about
   the deprecation.

Should it be included in Mason?

It is simple to implement and can safely be ignored by clients. The concept is in-line with Masons focus on improved client developer experience but might be better implemented differently (not that I know how).

mattupstate commented 10 years ago

Given my current understanding of "good" API design and hypermedia practices I would assume deprecation would be handled by API versioning. I'd be curious to hear about the initial reasoning or motivation behind this property, though.

JornWildt commented 10 years ago

You might just be right on that. But it could be nice to inform clients about changes to a service - in a formal way such that clients can take action automatically (for instance a background integration service e-mailing its care takers).

But why have it on the link as in HAL? If the client traverses the link then its certainly going to interact with the target resource - so why not put the deprecation message there?

Mason has the @meta element for communication stuff about the API. Maybe that's where Mason should have a @warning element for clients to react on?

JornWildt commented 10 years ago

Closing this. Added issue #6 instead.