ShinobiCharts for Android: how should we handle an evolving API?


#1

Our overall vision for ShinobiCharts for Android is that it should eventually be 1:1 feature compatible with the iOS versions. Obviously the APIs will never be identical, as the 2 products exist in different platforms and are presented in different languages. So as we add features are to the Android version, the API will evolve…

The iOS version is very feature rich, and some way ahead of its Android cousin, so we are releasing Android incrementally, adding features as we go, at a rate of roughly 1 release per month. This allows us to get the Android version out to those customers who only need the basics, without waiting for features that they do not need. Our roadmap for the product is still flexible, and we’d like to produce the features in order of greatest need first, so please tell us what you want! (We can’t promise specific features, but we’ll take your requests into account.)

With a flexible road map it is probably inevitable that sometimes we will want to change existing API, in ways that may impact existing customer code. Obviously we try to avoid this as far as possible, but I think it’s worth having a clear policy to deal with it, and sharing that with our customers. Here’s what we’re aiming for:

  • In general we will prioritise having a clear, simple API over rigorous backward compatibility. So in the (hopefully rare) cases where the existing API is unclear, we’ll change it.

  • When we make an API change, we’ll try to do it in two releases:

    • In the first release we’ll deprecate (using @deprecated)  the old API and add the new API
    • In the next release we’ll remove the old API. 

This should give you the ability to drop in new release versions with enough warning to make changes.

  • If it’s not possible to take that approach (e.g. if having both old and new API present at the same time would just cause confusion and inconsistency), then we would simply make the change immediately.
  • Any API changes will be noted in the ChangeLog.txt file which is part of the product download, indicating what changes have been made, why they have been made, and how you should change your code.  IMPORTANT! Always read the ChangeLog.txt file when you download a new version, either as a trial or a licensed update.

What do you think? We’d love to find out your views, and maybe start a debate on the subject. 

Robin Sillem

Lead Developer

ShinobiCharts for Android


#2

Hello Robin,

I would like to share my thoughts on this. First of I would like to say that even though Shinibi chart for android is in its infancy, it is at its core much nicer than the rest I could find at it. I am also evaluating the iOS chart package aswell, and it is really great altough not without its problems but those are most minor. It would be of create benefit for a Xamarin setup as mine that the APIs are kept similar as this will make the code sharing much better. (As of today I see over 80% code sharing between ios and android and this is also where all the complex stuff goes.)

If you are serious to supporting Xamarin, I think the most urgent matter is that the issue we have been discussing about in the thread http://www.shinobicontrols.com/forum/shinobicontrols/2013/11/android-chart-(xamarin-edition)-out-of-gref/ that concerns the global cross vm references. This is actually the only show-stopper for me, as we can live with fewer features in our initail release compared to the ios version, as I feel confident that you will eventualy deliver a feature set equivalent to iOS version.

However, the features I am lacking the most:

  • Discontinious datetime axis; cause plotting intraday stock/forex quotes looks really bad with large sections of flatlines.

  • Candlestick and OHLC series.

  • Annotations.

Best Regards
Lars Krog-Jensen


#3

Hi Robbin,

Do you have any date on when the next version will be released?

BR Lars


#4

Hi Lars,

We’re planning on releasing V1.2 next week. I don’t want to be more specific than that, the exact date will depend on getting it through our QA process.

Best regards,

Robin


#5

Hi Lars,

Deprecating old API in one version (and removing it the next) is quite short for normal situations, but I agree a neat API is of importance and this is still a feature uncomplete product, so if it does not happen to often, I guess that will do just fine.

Personally I would like to see the stack option for column and line series, that is what I miss the most.

Best regards, Harm


#6

Hi Harm,

Agreed, deprecating old API in one version (and removing it the next) is quite short for normal situations. One additional factor that led us to this timeframe was that (happily!) our customer base is growing well. So we felt it made sense to get the changes in early, as leaving it for (say) 2 release cycles  would potentially impact more people.

V1.2 is due out very soon, so here’s a reminder of what was deprecated in V1.1. (all of this is copied from the current changelog.txt file):

* API DEPRECATION. Axis.configureColumns has been deprecated (and will be removed in V1.2). Use Axis.configureBarColumns instead. This is a rename triggered by a simple consolidation of 2 near-identical methods in the iOS version.

* API DEPRECATION. Axis.requestCurrentDisplayedRange(T minimum, T maximum, boolean animation) has been deprecated (and will be removed in V1.2). Use Axis.requestCurrentDisplayedRange(T minimum, T maximum) or Axis.requestCurrentDisplayedRange(T minimum, T maximum, boolean animation, boolean bounceAtLimits) instead. CategoryAxis.requestCurrentDisplayedRange(int minimum, int maximum, boolean animation) deprecated (and will be removed in V1.2). Use CategoryAxis.requestCurrentDisplayedRange(int minimum, int maximum) or CategoryAxis.requestCurrentDisplayedRange(int minimum, int maximum, boolean animation, boolean bounceAtLimits) instead. This normalises and clarifies the requestCurrentDisplayedRange API, and is related to the behavioural change below.

* BEHAVIOURAL CHANGE. The behaviour of Axis.requestCurrentDisplayedRange(T minimum, T maximum) and Axis.requestCurrentDisplayedRange(T minimum, T maximum, boolean animation, boolean bounceAtLimits) (and their CategoryAxis equivalents) is subtly changed to increase clarity. In the 2 parameter overloads the calls respect the class-level values set by Axis.enableAnimation and Axis.enableBounceAtLimits. In the 4 parameter overload, you can explicitly override those settings for the call. Previously the class-level value was combined with the animation parameter in the (now deprecated) 3 parameter overload, leading to obscure and bug-like behaviour. Additionally, a true return value for all these methods now indicates the call was able to honour the requested range change, rather than having it limited by other API settings. The previous return value was poorly defined and not entirely consistent.

* API DEPRECATION. PieDonutSeriesStyle.getLabelFont, setLabelFont, getLabelFontColor, setLabelFontColor, getLabelFontSize, setLabelFontSize have been deprecated (and will be removed in V1.2). Use PieDonutSeriesStyle.getLabelTypeface, setLabelTypeface, getLabelTextColor, setLabelTextColor, getLabelTextSize, setLabelTextSize. This is a simple rename to bring the API into line with Android naming conventions, rather than word for word equivalence with the iOS version.

Best regards,

Robin Sillem