API

Owned by Adam Voakes
Last updated: Sept 14, 2022 by Karen Hogan (Unlicensed)
3 min read

We know that many of you prefer to utilise our current API, and therefore as our products grow we review our existing tools to ensure they’re delivering value to our users, and meeting our future needs.

The current API has become outdated and as a result we’ve made a few changes in order to move forward with new functions and improved technologies. This means that we’ve 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 and therefore we’re not planning to remove this until the end of 2021. The new API v2 will be introduced to work alongside the current one – this means that NO immediate changes are needed by our partners.  The new API v2 is available as a BETA release and 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 that we used in the current version. The BETA release will deliver like-for-like functionality that’s 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' re also taking the opportunity to remove any redundant functions in the current API due to their redundancy. The following have been removed:

·        Preferred Layouts

·        Connection User Links

·        Hierarchies

We will be introducing new functions into the API v2 in 2021 - User Layouts and Connection user links and we’ll share a timeline for these changes as soon as we have more information.

See our SwaggerHub account for technical information on our new API v2.

Note: SwaggerHub may have small problems, so if the page doesn’t display AFTER redirecting, just do an F5 refresh (sometimes you need to refresh a few times)

 

See some of our API Examples on our github repository.

We held an API Webinar in January 2021 to help provide an overview on the new API and demonstrate some if its features - you can find the Webinar here.

Key Partner Takeaways

  1. 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

  2. The new API v2 will be a like for like in terms of functions – but written in JSON rather than XML

  3. 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:

  1. We suggest you create your domain objects (e.g. PiUser) to encapsulate the information being returned from the pi API.

  2. A call to PiApi.createUser() will return PiUser, which is in your control

  3. PiApi.createUser() internally handles how to assemble a request to pi and assemble the 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)   } }