We know that many of you prefer to utilise our current API, and therefore as our products grow we review our exisiting tools to ensure they are delivering the most value to our users, and meet our future needs.
The current API has become outdated and we needed to freshen things up to help move it forward with new functions and improved technologies. In support of this we have introduced our API v2, which has been written in JSON rather than XML.
Our Approach
We know that many of our partners make use of the current API, therefore we are not planning to remove this until the end of 2021, and rather we are introducing the new API v2 to work in parallel alongside the current one – this means NO immediate changes are needed by our partners. The new API v2 is already available as a BETA release, which is included in the December 2020 version of the dashboard.
What does the new API do?
The new API v2 is based on a JSON file format, rather than XML as we used in the current version, however the BETA release will deliver like-for-like functionality found in the current API - but we will be expanding on that further in 2021. The key functions most commonly used include.
· Authentication
· User creation, updating and deletion
· Category creation, updating and deletion
· Role creation, updating and deletion
· Retrieving a list of Charts
We are also taking the opportunity to remove any redundant functions in the current API, so we do not just move the technical debt across, therefore we have not included the following API endpoints in the new version due to their redundancy.
· Preferred Layouts
· Connection User Links
· Hierarchies
We will be introducing new functions into the API v2 in 2021, around User Layouts and Connection user links to give you a flavour. A timeline for these will be shared in early 2021.
See our SwaggerHub account for technical information on our new API v2
Key Partner Takeaways
Our API is changing, but you don’t have to move to the new v2 just yet… we’re keeping the old one as it is in place for 12 months
The new API v2 will be a like for like in terms of functions – but written in JSON rather than XML
We will be introducing new functions into v2 further down the line, and we’d like to hear from you about things you’d like to see included
Considering Migrating To API v2?
To make the new API v2 easier to migrate to, we suggest that you use a wrapper to call the API. Here is an example of making a call within a wrapper.
The wrapper is an interface between your code and the calls to our API. With this in place, when switching to use our new API v2, all your changes will only be made inside the wrapper layer, meaning you can slowly migrate from the current API to the new API v2 and have both of them working for you at the same time if you wish.
Here is an example for creating users:
We suggest you create your domain objects (e.g. PiUser) to encapsulate the information being returned from the PI API.
A call to PiApi.createUser() will return PiUser, which is in your control
PiApi.createUser() internally handles how to assemble a request to PI and assemble PiUser to be returned
With such encapsulation, if you create PiUser in ten places in your application, and later on you want to change the usage of PI API, you only need to update your code in one place
e.g. upgrading from API v1 to v2 would be easy
e.g. if usercode in the response is renamed to username, you only need to assign response.username to PiUser.usercode
later on if you want to use Open API sdk tools to generate content to call pi api, this can happen in the wrapper as well
class PiUser {
Integer id
String usercode
// the rest of the fields that matter to your application
}
class PiApi {
static PiUser createUser(String usercode) {
String url // e.g. https://localhost:8224/panMISDashboardWebServices/api/user
String body // assemble the request and put usercode into the body
String response = Http.post(url, body) // in xml
Map data // converted from response xml
return new PiUser(usercode: data.usercode)
}
}