Hey folks. As we wind down the development of 3.2, we wanted to preview some of the new features and enhancements coming to the API. We're looking forward to your feedback on what you like, dislike, and what you'd change. Since we're talking about a product still in development, please know that this post is not necessarily representative of the final product; what's presented here is subject to change without notice.
In 3.2, we're introducing API v3. We're using the opportunity to make some changes to improve performance, resolve ambiguities, and reduce some complexity. As we were developing API v3, we noticed that it was difficult to identify which resources underwent changes. For example, we removed some response parameters in v3 from the GET Devices resource to improve performance, but unless you read the What's New page or specifically checked the documentation page for the GET Devices resource, you'd never know that a change was made to it in v3.
To make it clearer to know which API resources underwent changes in an API version, we've made some enhancement to the "Detailed Prime Infrastructure API Resource Documentation" (or as we refer to it internally, the index page). These changes allow for you to see, at a glance, how an API version has affected any given resource.
(Click screenshot to see details)
In the above screenshot, note that there's a new column on the far right, "API Version". It lists out all of the available API versions running on the appliance. When a resource is introduced, or has undergone significant changes, the version will be highlighted in dark blue. When it is available in a given version but did not undergo significant changes, the version will be highlighted in light blue. Each version listing is a link that will take you directly to the documentation page for that resource in that version. So, for the Devices resource, we introduced that resource in v1, and made a significant (and in this case, backwards incompatible) change to it in v3, so both the v1 and v3 links are dark blue. However, in v2, the Devices resource was the same as it was in v1, so the link is light blue.
(Click screenshot to see details)
In some cases, for instance, when we've deprecated a resource, we've removed it from API v3. In these cases, note that v3 listing is gray to indicate that the resource is not available in v3.
We've also made some enhancements to the pages that document each individual resource. Previously, after we introduced API v2, we changed the pages that document each individual resource to include version tabs, but we only listed tabs for versions where the resource was introduced or significant changes were made. For example, the Client Details resource had a v1 and v2 tab, but most other resources didn't. In 3.2, each resource's documentation page will now have a tab for every version. The tabs are color coded using the same scheme as we used above.
Again, using the Devices resource as an example, there is now a tab for each version, but only v1 and v3 are dark blue. We also added a note to let you know what was changed in the version. Following that note, is the table of the Response Parameters and the sample payloads, as before.
One other thing we'd like to note, in v2 we changed the JSON provider to get more consistent JSON output (the provider used for v1 would sometimes output JSON arrays as objects if they only had one member, or would change between strings and numeric data types depending on the content). One of the other benefits of the enhancements that we've made is that you can now get JSON sample payloads for the v2/v3 provider even if there have been no changes to the resource since v1. For example, the v1 page for Devices shows the following as part of the JSON sample payload
"manufacturerPartNrs" : {
"manufacturerPartNr" : "String value"
}
But on the v2 page, it shows the following
"manufacturerPartNrs" : {
"manufacturerPartNr" : [ "String value" ]
}
We hope this helps API developers understand and predict output from the API better.
Questions? Comments? Concerns? Please leave your feedback below!
6 Comments