Prime API versions

[smp]

I'm confused about something. I was looking at the PI3.0 API documentation, and I see now there is a section for API version "2.2". When did this come about? How exactly do the API versions get upgraded, and where do I need to look to find out that a new version has been released?

[Spencer Zier]

In Prime Infrastructure 3.0, we released API v2.  It uses a different JSON serializer which that is more consistent in behavior than the JSON serializer we were using in API v1.  We also made some backwards-incompatible changes to the Clients and ClientDetails resources (so accessing api/v1/data/ClientDetails gives different output than api/v2/data/ClientDetails).  For more information, check out the What's New page.

When you're looking at the Detailed API Resources page, you can filter by product version (the version of Prime Infrastructure) of when an API resource was introduced.  So for example, these are the resources that were introduced in Prime Infrastructure 2.2.

So there's two different versions here.  The API version, where we make backwards incompatible changes, and the product version, which helps you quickly identify what was added in each release of Prime Infrastructure.  I hope that clears up the confusion.

[smp]

Hi Spencer, and thanks for the response. Unfortunately I just became more confused. Perhaps I did not clearly articulate my question, so let me try it a different way.

I get that there are two versions - the product version and the API version. And I get that API v2 was released with PI3. But I was surprised reading the What's New documentation that there /was/ an API v2.2. I don't see reference to it in the release notes for product patch 2 that the API version was upgraded. Where would I look to tell me that API v2.2 was released (as opposed to API v2)?

[Spencer Zier]

Are you referring to the "What's New in the Prime Infrastructure 2.2 API" header?  That's just referring to Prime Infrastructure 2.2.

[smp]

Ooohhhhhh!!! That header looks to me like it's referring to version 2.2 of the API, not the product!

So the most current versions of both the product and the API are 3.0 and v2 respectively?

[Spencer Zier]

Correct.

[smp]

OK, sorry.

> "What's New in the Prime Infrastructure 2.2 API"

The heading references the API, so it lead me to believe it was referring to the API version, not the product version. You might consider calling out the product version versus the API version to make things more clear, something like this:

"What's New in the Prime Infrastructure 3.0 (API v2)"

Also I was reading that document from top-to-bottom, thinking that the newest information was at the bottom.

Thanks for clarifying.

[Spencer Zier]

Perhaps "What's New in the API for Prime Infrastructure X.X".  Yeah?

[smp]

I think that would help, yes.

[smp]

I do like the new heading description of the What's New section - "What's New for the API in Prime Infrastructure 3.1". This is much more clear. Thanks very much for making that enhancement.

However, I do not see any mention of API changes in the 3.1 product documentation. Did I miss it somewhere?

[Spencer Zier]

Not sure what API changes you mean.  We did introduce some new resources, which is mentioned on the What's New page, but I take that's not what your referring to?

[smp]

Hi, no it's not. Sorry I was not clear again.

When I read the release notes for a new product version, I expect to see some mention that there are updates to the API (only if there are really are any API updates). That is my trigger to go out and look at the What's New page of the API doc. However, I could not find any mention of API updates in the 3.1 product release notes, so I did not read the What's New page of the API doc until way after we had upgraded to 3.1 of the product. I'm just wondering why there was no mention of API updates in the product release notes? Or maybe there was and I just missed it.

[Spencer Zier]

Ah, ok, gotcha.  I'll circle back to the team responsible for the release notes.

[smp]

You've been great - thanks so much for your responsiveness to this community!