Future Migration

Owned by Karen Hogan (Unlicensed)
Last updated: Jun 21, 2021
2 min read

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 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)

  }

}