Hello again! We'd like to continue our series of blog posts with another Prime Infrastructure 3.2 preview. Please leave any feedback or questions you have in the comment section below. Just like in our last post, 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.
As we discussed in our previous post we are introducing API v3 in Prime Infrastructure 3.2. A large part of the reason we decided to introduce v3 is to make some needed but backwards incompatible changes to many of our resources. However, we also wanted to take the opportunity to introduce a couple API-wide changes in v3. These changes will impact all interactions with the v3 API, regardless of whether or not the particular resource being used was updated for API v3.
The first change we made was to how we verify input. Previously, in API v1 and v2, if you made a mistake in specifying a filter parameter the API would still accept your request, ignore the parameter, and give you a result. This caused confusion for a lot of users because they didn't realize that their filter was ignored. In some of the most pernicious cases, the user had spelled the parameter correctly, but it wasn't capitalized correctly. For example, when querying the GET data/Devices resource, some users would mistakenly request v1/data/Devices?devicename=test rather than v1/data/Devices?deviceName=test.
This behavior could be overridden; the .strict query parameter could be set to true, which would cause the API to validate all of the provided query parameters. But many users were unaware of the existence of this parameter and did not think to use it when facing API responses that didn't seem to match up with their requests.
To address this problem, in API v3, the .strict parameter will now default to true, rather than false. So, by default, all requests to the v3 API will have all query parameters validated. We hope that this change will help API users quickly identify and resolve problems with their queries.
The next change we made was to how we support paging. There are two methods for users to specify paging parameters: by query parameter and by request header. Based on our engagements and interactions with customers, we know that virtually all of them use the query parameter method of paging. So, in API v3, we're removing request header paging. We believe this will help keep our code simplified and maintainable, and have no negative impact on the vast majority of our users.
One other change coming in Prime Infrastructure 3.2, separate from API v3, is integration of our documentation with DevNet. Over time, we've had a lot of great questions and discussions take place in this community about the API. But, when you're looking at the documentation for a particular API resource, you might not always be aware that there may be a thread on DevNet with the answer to your current question or problem. So, we've included links to relevant DevNet discussions when viewing the documentation page for a resource. The list of links will show up just under the "Resource Information" infobox. Here's an example of what it looks like for the GET data/Devices resource.
The list is sorted with the most recently updated discussions at the top, and the oldest at the bottom. The discussions chosen to appear in the list are selected by tags, to ensure they are relevant to the resource documentation you are viewing.
Because communities.cisco.com does not support cross-origin resource sharing, all of the requests for DevNet discussion lists pass through Prime Infrastructure. We're aware that in many environments, the Prime Infrastructure appliance may not have direct access to the Internet. To enable this feature to work in these environments, we make use of the proxy that's been configured for Prime Infrastructure. If the proxy has not been configured, the DevNet discussion box will let you know how to configure it.
All right, that wraps up this blog post! As before, we look forward to reading your questions, comments, and critiques!