Add a "Versioning" section to the Agency spec as in the Provider spec

[Retzoh]

Is your feature request related to a problem? Please describe.

There is no specification on how versioning works for the Agency API :
A provider cannot specify the version used for the data he is trying to push.

Describe the solution you'd like

For consistency, I propose to use the provider API versioning system, where the version used is specified in the request Accept header.

If we re-use the application/vnd.mds.provider+json media-type or rename it to application/vnd.mds+json in the provider spec, we could easily centralise the versioning spec in one place and expand it to further APIs.

Is this a breaking change

A breaking change would require consumers or implementors of the API to modify their code for it to continue to function (ex: renaming of a required field or the change in data type of an existing field). A non-breaking change would allow existing code to continue to function (ex: addition of an optional field or the creation of a new optional endpoint).

• I'm not sure

We can decide to make it breaking or not :

Adding implicit support for the previous minor version like in the provider spec makes it non-breaking :

Since versioning was not added until the 0.4.1 release, if the Accept header is not set as specified above, the Agency API must respond as if version 0.3 was requested.

This would stay consitent with the two concurrent version support from the release guidelines.

Enforcing this retro-actively would make it breaking.

Impacted Spec

For which spec is this feature being requested?

• agency : yes

• policy : we could add it there too, so a provider requesting the API can ask for a specific version in return

Describe alternatives you've considered

The classic alternative would be to enforce a version number in URLs.
But this would be inconsistent with the provider spec and so far, MDS does not put constrains on API URLs outside from the endpoint and query-parameters.

Additional context

None

[Retzoh]

Hi @sarob, this issue should be labeled "Agency"

[marie-x]

Agreed, I'll update Agency and Policy in the 0.4.1 timeframe. Thanks @sarob.

[Retzoh]

@Karcass have you made any progress? I would be happy to help.

[marie-x]

@Retzoh I have not, I have been heads-down on the Agency/Provider naming reconciliation. If you want to take a swing at it, please do!

[Retzoh]

I will propose a PR this week.