We are working on a project which will be powered by discourse for the backend but will have various apps which will depend on its API, potentially, changes to the API could break our upstream apps by adding, changing or removing data which they depend on.
Is there any plans to implement a versioned Restful API similar to what the webui has for plugins? I imagine this is quite a concern for any one else writing applications which rely on and consume discourse data.
I know this would be quite a major undertaking one which we might be able to take on if it would be interesting to the community.
If this were to be done, I imagine the best way to start would be via a plugin which added the required versioned api functionality by duplicating the serializers and then creating a rather complicated inheritance (yes not very rubyesque ) chain to provide the required values at various versions and each version validated against a json schema to ensure compatibility.
There are many more complexities to overcome such as removed features, or parts where core discourse has been changed but those can be addressed as and when they come up by something like the rails gem graveyard etc.
I have seen oddities in the past in java and IOS apps if data exists which it wasn’t expecting which is why i added “added”. Our usecase is more data which is removed, moved or changed value type from a set of expectations. Is there a discourse policy for api changes? (this may be a mute issue if there is )
Hey Paul! Good question. The short answer is that in the near future we don’t have any plans to version the api.
Because discourse itself consumes the same public api I don’t see a point in versioning it separate from the actual discourse versions that are released. I do see the problem you are trying to address though because I have experienced them myself dealing with various API’s and I’m sure there are some improvements we could make like maybe leaving an old endpoint around longer but make it deprecated in addition to adding the new endpoint that replaces it. I think that problem could be solved though through better api documentation and noting what changed between discourse versions.
While obviously it would be great if we could tell you exactly what changed api wise between discourse versions (A goal I do want to achieve at some point, but probably won’t happen until we have a good way of automating the generation of api docs), perhaps if this is a serious requirement for your business needs I think it would be good to setup a staging server for your forum where you can roll out any new version of discourse to, and then test all your api calls before upgrading your production forum.
) chain to provide the required values at various versions and each version validated against a json schema to ensure compatibility.
)