Which ESRI Javascript API Version to Use – 3.x vs 4.x

Which ESRI Javascript API version should you use for your next mapping app? I wish it were as simple as just using the most up to date version. And maybe it will be for your situation. But there are a few considerations to address before pushing ahead.

Start With Your Goal

Always start with your goal. What do you want the app to look like and do? Probably, the biggest question you should ask yourself is whether you will be creating a 3D app or a standard 2D app?

As of this post, the 4.x API is at version 4.11. According to ESRI’s API Capability page, version 3.28 (the latest 3.x version) doesn’t support 3D rendering. Version 4.11 only has partial support for 2D. So, if you’re planning to create an app that supports 3D visualization in any way, you’ll need to use 4.11.

On the other hand, if you are only supporting 2D visualization you’ll want to use the latest API that supports all of the other functionality you might want to use. This is really important to consider if you’re thinking about migrating existing 3.x code to the 4.x world. You would hate to get deep into the conversion only to find out a critical component you rely on is not yet supported.

Check out ESRI’s functionality matrix to determine if 4.11 is implementing all the functionality you need right now. ESRI’s stated goal is to eventually have 4.11 eventually exceed the functionality of the 3.28 API. But until it does, you’ll want to proceed with at least a little bit of caution.

Consider Your Time

Another thing you will want to think about is the time you will spend getting up to speed on the syntax changes that version 4.11 brings. Right away, when creating a basic map with 4.11, you’ll notice that you now have to not only create a map but a map view (or map scene if it’s a 3D app) in order to get anything to render.

With the old 3.x API you would simply declare the map object and pass in a reference to the HTML element you want to use to render it in. As of 4.11, the Map object is now simply a container for the various layers you want to associate with the app you’re creating. There is now a new class called View that manages UI methods for your app like rendering the map within the HTML element and placing components (like widgets and images) on screen.

I like most of the new syntax changes that I’ve seen in 4.11 but I realize these slow down my development time as I get used to them.