diff --git a/SUMMARY.md b/SUMMARY.md index c5b8674..069f0ff 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -15,4 +15,5 @@ * [Loose Coupling](core-principles/loose-coupling.md) * [Rules for Extending](core-principles/rules-for-extending.md) * [Versioning](core-principles/versioning.md) + * [Content Negotiation](core-principles/content-negotiation.md) diff --git a/core-principles/content-negotiation.md b/core-principles/content-negotiation.md new file mode 100644 index 0000000..5511b3f --- /dev/null +++ b/core-principles/content-negotiation.md @@ -0,0 +1 @@ +# Content Negotiation diff --git a/core-principles/robustness.md b/core-principles/robustness.md index a1f1e30..093f410 100644 --- a/core-principles/robustness.md +++ b/core-principles/robustness.md @@ -1,9 +1,9 @@ # Robustness Every API implementation and API consumer MUST follow Postel's law: -> "Be conservative in what you send, be liberal in what you accept." +> _Be conservative in what you send, be liberal in what you accept._ > -> – [John Postel](https://en.wikipedia.org/wiki/Robustness_principle) +> _– [John Postel](https://en.wikipedia.org/wiki/Robustness_principle)_ That is, send as little as possible and be tolerant as possible while consuming another service ([tolerant reader](https://martinfowler.com/bliki/TolerantReader.html)). diff --git a/core-principles/versioning.md b/core-principles/versioning.md index 971048c..acbb9f2 100644 --- a/core-principles/versioning.md +++ b/core-principles/versioning.md @@ -1,2 +1,30 @@ # Versioning +> _The fundamental principle is that you can’t break existing clients, because you don’t know what they implement, and you don’t control them. In doing so, you need to turn a backwards-incompatible change into a compatible one._ +> +> _– [Mark Nottingham](https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown)_ +Any change to an API MUST NOT break existing clients. + + +## Representation Format Change +> A representation format is the serialization format (media type) used in request and response bodies and typically it represents a resource or its part, possibly with additional hypermedia controls. + +A change to a representation format MUST follow the [Rules for Extending](core-principles/rules-for-extending.md). + +If the change can't follow the Rules for Extending the representation format media type MUST be changed. If the media type has been changed the previous media type MUST be available via [Content Negotiation](core-principles/content-negotiation.md). + +#### Example + +Media type _before_ a breaking change: + +``` +application/vnd.example.resource+json; version=2 +``` + +Media type _after_ a breaking change: + +``` +application/vnd.example.resource+json; version=3 +``` + +## Resource Change \ No newline at end of file