API backward compatability

[ByronZ]

I have been using Meraki API since v0 and it worked out great. I mainly use it in PowerShell for new branch deployments involving MX, and MS with different VLANS. I created this PowerShell script a while back and has let other members in my team to use it. Now that the API has been improving a lot, and adding more functions to it, which is great. In the same time, I also need to keep up with the new changes, since it is not backward compatible, which means my job a little more challenge to keep up. I love working with PowerShell, but I am not sure full time developer. Every now and then I need to revisit PowerShell and Meraki API page to keep up because my team keeps coming back to tell me it is not working. 

Now my question is how hard is it to keep the API backward compatible? Or is it just me who is struggling to keep up with the API updates? 

Thanks

Byron

[John_on_API · Accepted solution]

I'm glad to hear you've had a good experience with v0! We have not made many (if any) changes to v0 for some time now--I would be surprised if you were suddenly having issues with v0. If I understand your question, you are asking why v1 is not backwards compatible with v0, or why migrating to v1 requires changing your code. I'm glad you asked.

For context, we released API v1 last year, which is our current major version. API v1 is a fundamentally different structure that offers a number of improvements over v0, and is not backwards compatible in most cases. One of the major goals in v1 is to organize the information more intuitively than the fairly flat structure that v0 provided. Therefore, we are releasing new features exclusively on v1 and encourage our customers to adopt v1 at their convenience to take advantage of the additional features. Granted, v0 still works and is available for legacy scripts that still use it.

So to answer your question directly: it's effectively impossible to not have breaking changes between major API release versions. In fact, avoiding breaking changes defeats the (perhaps entire) purpose of versioning the API.

We avoid breaking changes within a version number. It is rare to make a breaking change within a given version number--it would normally be a result of a bug that requires a breaking change to fix, and never just for the sake of it. In any case, adaptation and evolution is an inevitable fact of the software development lifecycle. Ideally, major API release versions (e.g. v0, v1) have the lifecycle of a piece of hardware, or longer. In practice, the lifecycle of an API version will vary based on the industry. 

Have you seen our interactive documentation site? It covers all of the endpoints in detail, and is searchable. We're always looking for feedback on our documentation and how it can make our developers' lives easier--we fully understand that most folks using a network platform API will be netadmins first, and developers second. In any case, keeping current on updates to the API is similar to keeping current on a Cisco certification, where the topics, and areas of focus, change over time.

You can also post questions here about the specific things you'd like to do with the API, and there are a lot of folks here willing to help! Long term, I think you'll find that it's overall easier to get things done with v1, despite the adjustment phase.

[ByronZ]

@John_on_API ,

Thanks a lot for sharing all those reasons behind the versioning. It helps a lot. Just had a rough day after chasing those errors.

The interactive document site looks very nice. I will kick some tires on it. I normally use Postman to test the API. Now I got a new tool to test it.

One thing I am still not clear is: when should I be using v0, and v1? It is very confusing to me.

An example is the switch ports configuration. I found that /devices/{serial}/switchPorts no longer works regardless it is v0 or v1 that I tested with. Finally, I changed it to v1 with /devices/{serial}/switch/ports and it works.

Another one is if I use v1 on /organizations/$OrganisationID/networks to create a new network, it failed. If I changed it back to v0, it works.

Unfortunately, PowerShell Invoke-RestMethod doesn't really return the error stream nicely to let me know why it failed with v1 except saying it is a 400 error. Anyway, the workaround I have is that I am using both v0 and v1 in my PowerShell script. It is just getting messy.

[PhilipDAth]

>One thing I am still not clear is: when should I be using v0, and v1? It is very confusing to me.

You should exclusively use V1 in anything new.  V0 will eventually be turned off.

[PhilipDAth]

I've haven't had to touch any of the v0 scripts.  They just kept working.

However, I have changed to working exclusively in Python now using the Python SDK.  I did this because in the Meraki world it is a "first class" citizen, and has the best support.

I would suggest you change over as well to get improved support.

[ByronZ]

@PhilipDAth 

Are you using /devices/{serial}/switchPorts in your scripts? Mine doesn't work anymore.

I do believe Python has better support with Meraki API. I am working in a Windows shop, and PowerShell is more of a natural fit for other tasks. For many simple tasks like,reading a csv file, extract data from it, manipulate it, it is very straightforward. Of course, it could be just me not know the tricks in Python. 

[Steinbep]

@ByronZIf you know PowerShell inside and out, just use that.  It will be harder to maintain in the long run though. 

The fact that Meraki maintains a python sdk for you, makes the change so much easier. You don't have to maintain your own requests. I started with the Meraki API several years ago and it kick started my python programming/automation journey.  Python seems to be the language for network automation and honestly it is super easy to learn.

As for csv files, python has a standard library for working with csv files and its super easy to learn. 

Just my 2 cents.

[ByronZ]

I think PowerShell is one of the most powerful things in the Windows environment. I love using it. Since Python has the best support from the Meraki community, I think I will take the advice, at least to test it out in Python. Hopefully it won't take long to migrate my almost 1000 lines PowerShell script over.

Thanks everyone here.