For anything to be easy to learn and use, it needs to be as intuitive and consistent as possible. Over the past 20+ years, many APIs in Xojo have been added that were not intuitive or consistent. While longtime users have gotten used to them, they can make Xojo difficult to adopt for new users. API 2.0 is our solution.
We did this by creating a sensible set of API naming guidelines and then applying them to our existing APIs. APIs that followed the guidelines were left alone. Those that did not, were changed to meet them. Hindsight, as they say, is 20/20. Looking back, it would have been great had we established these guidelines way back in 1998 before we shipped v1.0 but we didn’t and the fact that we didn’t is no reason to avoid it now. We always plan for a long future ahead of us and thus have to be willing to make changes to make that future possible. That we are still here 20+ years later suggests we are doing something right.
If you are one of those long time users who has grown accustomed to the inconstancies that API 2.0 addresses, you might be wondering if there’s any value for you in using it. The answer is absolutely yes! While it will take a little time for you to get used to the new APIs, what you will find is that you become increasingly more productive because they are so consistent. You will find (as I did) that you can guess at what the API is and likely be correct. I personally made 95% of the Language Reference updates for API 2.0. The documentation wiki does not auto-complete so I had to double-check all the code I was updating. In no time I found that I rarely made errors because API 2.0 is so consistent. You will absolutely see productivity gains once you have used it for a short time.
While API 2.0 is a major step forward for Xojo in terms of intuitiveness and consistency, for those of you with large projects you may feel like migrating is a daunting task. Depending on size, there can be anywhere from a handful to thousands of deprecation warnings to deal with, each being a particular change that could be made.
You might be assuming you absolutely must upgrade your projects but that’s not necessarily the case. How much of a project you update and when depends significantly on how important it is for you to update your existing projects to API 2.0.
First, it’s important to understand that most of the deprecated APIs are going be around for a very long time. It’s possible (perhaps even likely) that they could continue to exist for the entire life of your software project. You could decide not to upgrade any portion of your project or only upgrade portions that require it and then only when necessary.
Many deprecated APIs still share their implementation with the API they replace. A good example is RecordSet.MoveNext and RowSet.MoveToNextRow. If a bug is fixed in MoveToNextRow it will also likely be fixed automatically in RecordSet.MoveNext even though that method is deprecated.
Should you find a bug in a deprecated API you are still using, first try the new, replacement API and see if the bug is no longer reproducible. If that’s the case, you have an immediate solution: just upgrade that one usage of the deprecated class to the new one.
If the bug still exists in the new, replacement class, please report the bug using Feedback. Once fixed, there’s a chance that it will be fixed in the deprecated class as well, assuming it still shares its underlying implementation with the old deprecated class which, again, is true in many cases.
When deciding what to do regarding API 2.0 and any particular project, your options are:
- Not Upgrading – You could choose not to upgrade an existing project to API 2.0. You could then only upgrade portions of it should that become necessary due to a bug fix or the introduction of new features.
- Upgrade Incrementally – Another option is to upgrade your code incrementally as an extra step before refactoring or adding new code to a particular part of a project. This is the path we have chosen for the Xojo IDE as it’s a very large project that would take many months to upgrade if we did it all at once.
- Upgrade All At Once – Finally, you may decide to go ahead and upgrade your entire project all at once. This has the advantage of allowing you to focus exclusively on the new APIs and no longer have to switch between the old and the new when going back and forth between older projects and newer ones.
If you’re choosing not to upgrade an older project or do so incrementally and you find seeing the deprecation warnings distracting when you use the Analyze Project feature, you can turn off these warnings by choosing Project > Analysis Warnings.
API 2.0 was introduced with desktop projects but it will be coming to web projects in Web Framework 2.0, for mobile in Android and eventually iOS as well. As a result it will be important to use the new APIs but for many of you, using them only with new projects and/or sporadically with older projects, may make sense.
API 2.0 is a huge change and change can often be difficult. There’s certainly a lot of comfort to be found in the familiar. Still change is sometimes necessary to keep things moving forward. Fortunately, in the case of API 2.0, we have designed it so that you have tremendous flexibility in terms of what options you choose for existing projects.
- Read more blog posts about this transition.
- UserGuide: Moving Forward with API 2.0
- UserGuide: API 2 Guidelines