Should new APIs be consistent with existing Java APIs or make use of Kotlin?

[louwers]

I would like to start a discussion about new APIs that we add to the (Android) toolkit. The Android platform of Mapbox GL Native codebase was written purely in Java originally, after the fork we have not done much expansion of the API surface since. When we completely redesign a set of APIs, I think it makes sense to re-imagine it with Kotlin in mind (see e.g. the annotations design proposal). When adding one new API method to an existing set of APIs, should we remain consistent with the original Java APIs, or do we want to create an API method that are more natural for Kotlin?

For example, in #2516 a new method is added for fetching a single (offline) region. The API implemented in the PR uses an interface to define the object the callback will look like.

    /**
     * This callback receives an asynchronous response containing the
     * OfflineRegion in the database or an error message otherwise.
     */
    @Keep
    interface GetOfflineRegionCallback {
        /**
         * Receives the offline region.
         *
         * @param offlineRegion the offline region
         */
        fun onRegion(offlineRegion: OfflineRegion)

        /**
         * Receives the error message.
         *
         * @param error the error message
         */
        fun onError(error: String)
    }

This is in line with the existing API, but a more Kotlin friendly API would use a more functional approach with a callback with a single Result<OfflineRegion?> parameter that can communicate if there is a result, if there is an error or if there is no result but no error either.

What do you prefer? Consistency or incrementally adopting Kotlin?

[boldtrn]

I am personally voting for Kotlin Style APIs. I think most of Android is already focused on Kotlin.

[louwers]

Note: we are already using Kotlin. But should new APIs use a Java style (to be consistent) or be natural to use from Kotlin first and foremost?

[boldtrn]

Yes I know, IMHO we should also use Kotlin style. The Kotlin right now was essentially mostly "just" converted to Kotlin from Java. Sorry if I was a bit unclear in my answer :)

[louwers]

Thanks for clarifying and thanks for sharing your view!

[lepigocher]

I use MapLibgre GL JS from more than a year now and it's one of the best Open Source project I have used until now.
From a few days, I started to look at the Android native version and it's a nightmare. First both API are not 'in sync' and it's really diffuclt to find information. The documentation is useless because as a beginner what I need it's NOT a huge list of API but samples!

Now considering your question, I testify as a begginner with Android than it's another problem with this platform. Many samples use Java and it's difficult to understand some samples when two languages are used to do the same things.

Normaly, Google recommend from 5 years now to migrate to Kotlin (https://developer.android.com/kotlin/first) and so I expect to found samples and projects using Kotlin BUT we have to do with legacy code! So it's not a simple problem.

IMHO, the Android native project should be rewrited from scratch using Kotlin and because it's a lot of works the team should try to 'pair' all API (JS, Android, iOS, ...). Mapbox have do this a few month ago, the last version is full Kotlin (https://github.com/mapbox/mapbox-maps-android).

I understand that this is not really an answer to the question asked. But the problem is broader than simply choosing a way to write a function or more generally the future code of the existing API.

[louwers]

Although we strive for having the same features available on all platforms, a different API per platform is expected and arguably desirable because developers for each platform come with their own expectations (Kotlin APIs look different than Swift APIs which look different than TypeScript APIs). That said, MapLibre Native has seen significantly less feature development than MapLibre GL JS. We track (lacking) parity, but we don't have many resources to work on it. As is often the case in open source, functionality gets implemented when someone has a particular need.

I agree that examples are the best documentation. We have three examples here right now, but the best source of examples is the test app as well as the tests in this repo. Suggestions for other examples are welcome. Please suggest them here and I will make an issue for them. We have (bounty) budget available to work on documentation.

Android native project should be rewrited from scratch using Kotlin

I believe rewriting from scratch is not a good option, even if we had the capacity to do this. Hence my preferred approach of incremental migration.

[lepigocher]

I've already found these examples but it's definitely not enough. This allows you to see in 3 minutes that you can display a map with a style but that's all. Especially if, like me, the user already has a good knowledge of the general operation via the JavaScript version.

I can make suggestions but be careful the list will be very long! :) Because in a single day I already have a good dozen questions on simple subjects that are very well documented in JS and totally absent in the Android version.

When I say that APIs should be 'paired', I don't actually mean exactly the same. Obviously there are differences from one language to another. What I'm waiting for is equivalence to do the same things from one platform to another. I must not be the only one in this situation?

Finally, regarding the total rewriting I understand the reluctance that one may have. Especially since I already experienced this kind of problem a few years ago with the largest Open Source project under .Net (DotNetNuke). Part of the team did not want to introduce changes to the infrastructure purely for backward compatibility reasons. While others (me included) wanted significant changes in both infrastructure and functionality. The first ones finally won but it's what we call a 'Pyrrhus victory'. In the end, the project never took the turn towards new technologies and good practices (DI, CI, etc.) which means that the users left little by little and the project is now dead.

Completely redoing this kind of project is always a very difficult decision, but it can make it possible to make real, important changes that will be particularly useful in the future. In addition, users can more easily understand that they should change important parts of their code - if and only if - this allows them to introduce benefits later. Otherwise you will always have disappointing comments from both sides (those who want a change and those who want their current code to be maintened without changes).

[louwers]

I can make suggestions but be careful the list will be very long! :)

That's great! We need input from users to improve the documentation situation.

regarding the total rewriting I understand the reluctance that one may have

It's not just reluctance. Someone needs to pay for it, and I don't think anyone wants to pay for a full rewrite. MapLibre Native is under active development, but it's mostly the rendering core that is seeing development. It is always easier to make a business case for more features, better performance, wider deployment possibilities, rather than rewriting just to have a nicer API for developers. Note that we're not against rewriting things in principle, feel free to create a design proposal if you think you can pull this off, but we don't have the resources for that.

[JRWilding]

Consistent API. If you introduce new API paradigms bit by bit, you'll have a very misaligned API for years, which is confusing.

You'll then have to choose:
a. update old style APIs as and when they require changes - each release then has breaking changes
b. make one breaking change in the future where you update all of the old style apis

Since b > a there is little advantage to having some of your APIs already updated.

Also, I dunno if it is still the case, but using the kotlin Result class required setting a compiler flag a couple of years ago, to encourage people to make specific result classes (I guess)

[louwers]

We can shift to a different API without a breaking change by deprecating old APIs and introducing something new.

But I agree that it is better to introduce a whole new set of consistent APIs instead of doing this incrementally and only for new APIs.