Version The API

[samdeane]

As discussed in various threads on Discord and/or the forums, the API should be versioned (probably using semantic versioning).

This would have some major benefits:

• a new, cleaner v2 API could be introduced without breaking old scripts
• the controller could tell the game which major version of the API it wants to use
• scripts could query the minor version at runtime to work around problems when deployed in different environments (eg on the PTS, or internal staging servers)

Another benefit of this is that it would be possible to silently roll out new API features to the live servers, without them being picked up by all scripts.

In addition to picking API v1 or v2 in the controller's UI, it would be possible to allow users to pick a prerelease bleeding-edge version, which would enable new functionality that's under test. It would also be possible for users with special privileges (eg the game developers) to pick a internal API version that only they could use.

So a new feature might first be rolled out to the internal API version. Once it had been verified as working without unexpected consequences, it could be promoted to the prerelease API version, for the Lua development community to test. Once any feedback from that had been taken on board, and any regressions fixed, it could be incorporated into the official v2 API - at which point all constructs in the game using the v2 API would get the new changes.

This would provide a safe mechanism for testing scripts in the live server environment, before making them part of an official API update. Which might help a bit with some of the regressions we see.

[samdeane]

Behind the scenes, of course, this would add some complexity as you'd potentially have to maintain parallel API implementations. I have been in this situation and understand that it's not simple.

However, I've also been in the situation where I'm stuck maintaining an old API which is no longer fit for purpose. The worst thing about that is that the rest of the world keeps moving. So you are forced to add more stuff to the old API, further entrenching it. Literally every new thing you add makes it harder to fix the API, and less likely that you'll ever be able to wipe the slate clean. Meanwhile for every day that the old API exists, more clients use it, making it harder still to migrate everyone to a new one.

Really the only solution to this problem that ever works is to enable a mechanism for introducing a new API whilst continuing to maintain the old one, at least for a transition period. The trade off is more work in the short term vs perpetual pain in the long term!

[NQ-Ligo]

Hi there!

We already answered this topic on the forum some time ago, but we'll try to summarize our position on this topic here ;) To be clear, we don't have the resources to implement and maintain this kind of versioning on Lua API.

So currently we are able to implement new Lua APIs and rework existing things, but without breaking things. It works for a while, but we will have to break things sometimes anyway to improve or rework.

[samdeane]

Even if you don’t have the resources to keep an old API version working indefinitely, versioning is the only sensible way to manage a transition between it and a new one.