What is GPM's API?
An API (Application Programming Interface) is a very common term nowadays used to refer to an application developed so users can consult information related to the business in a programmatic way. It has become relevant since more and more tasks require information through custom made software with very particular needs of the business in mind. That is why GPM has its own public API, so users can access and use it to start implementing automated tasks.
The API's documentation
The main source of information on how to programmatically access specific resources of the API can be found in its own documentation at https://nzgpm.gensolve.com/api/. Since this is an application that is meant to be used by developers, it follows developers standards when referring to resources, requests, parameters, etc.
Getting Started
1. In order to get started using the API, a system user needs to have a User Access Role associated with API Access and API Management privileges. The API management privilege is needed to configure the API and to grant API-specific privileges. It is also a good idea to provide access to the Administration menu on the main form, since most of the initial settings will be done from GPM windows interface.
This can be done via Administration >> User Access Roles >> New Access Role (or edit an existing role by clicking on the 
icon on the role) >> Windows tab >> Grant the permissions under the APIs section and also the permission Administration Menu under the Main Form and Reports section >> Save
2. Similarly, you can configure the API privileges for a User Access Role to provide access only to specific endpoints or methods via Administration >> User Access Roles >> New Access Role (or edit an existing role by clicking on the icon on the role) >> API tab >> Select a resource or group of resources from the EndPoint drop-down and a method. The EndPoint drop-down displays the available resources/group of resources in the API and the available HTTP verbs/Methods to be used along with these resources.
Examples:
A. If you wish to grant full access to all of the resources of the API, you would select the "/*" option on the EndPoint drop-down, and if you want to grant access to every kind of operation (GET: read, POST: create, PUT: update) select the "*" option on the Method drop-down, but if you just want to grant reading permissions, then select the GET option.
B. If you wish to grant access to a group of resources, i.e. all of the EndPoints associated with Appointments, then select the resource group "/clinicians/*".
C. If you want to give access to a specific EndPoint, e.g. "/appointments/by_date", select this option on the EndPoint drop-down. Notice that the Method drop-down no longer provides all of the methods available but only the one that is directly related to this resource, in this case GET.
3. Make sure that the system user that will be used to access and manage the API has this role associated to it. You can check this via Administration >> System Users >> Get Data >> Click on the first 
icon >> Click on the Access Privilege drop-down and select the role created/edited previously >> Save.
4. Now, when logging in as that system user, you should see the button API Configuration in the Administration menu. In this interface, the user will be able to access the API's documentation, download the API's latest OpenAPI.json file, get relevant information such as the secret key which will be needed to get an authorization token, and more. In this article we will review this interface by sections, the first one will be Allowed Access Roles.
Allowed Access Roles
By clicking on Get Data on the Allowed Access Roles section, you will see a list of all the User Access Roles that have the API Access privilege. API privileges can also be configured from this window as shown in Getting Started point 2.
1. Click on the icon next to the role to which you want to add API privileges >> Go to the API tab >> Select a resource or group of resources from the EndPoint drop-down and a method. The EndPoint drop-down displays the available resources/group of resources in the API and the available HTTP verbs/Methods to be used along with these resources.
2. After adding the desired API-specific privileges and saving, you will see two things when selecting a role on the list: the system users associated with that role and the API Privileges granted for this role.
3. If you want to revoke API access on an access role, just click on the 
icon next to it. This operation will not delete the role, just revoke the API Access privilege to it.
Note: as soon as you edit or remove API access from an access role, these changes will be saved automatically so there is no need to hit the Save Configurations button.
Allowed System Users
In order to be able to see which system users have access to the API, first view the list of allowed Access Roles via Administration >> API Configuration >> Get Data and then select one of the roles to see if it has any users associated. If no users have been added though, you can click on the Add User button to associate a system user with one of the Allowed Access Roles.
1. Add User >> Select a system user from the users drop-down >> Select one of the Access Roles from the roles drop-down. If no role shows up on this drop-down, it means that there are no API Access Roles. You can click on the 
icon to create a new Role and grant it the needed API Access permission >> Save.
2. After having associated a user to a role with API Access, you can click on the role under the Allowed Access Roles section to see that the user appears under the section Allowed Users.
3. If you wish to revoke API Access for a system user, just click on the icon next to the system user's name. This action will not delete the user, just de-associate the access role from it.
4. If you wish to change the access role from a user, click on the icon. The Access Role interface will be displayed and you can change the role.
Note: as soon as you add or remove a user, these changes will be saved automatically, so there is no need to hit the Save Configurations button.
IPs Whitelisted
As part of the API's security measures, you must configure a set of allowed IP addresses that can access the API.
1. Click on the Add IP button. A window with a simple text box and an Add button allows you to add all the addresses that you need. Optionally, you can click the Add My IP button if you want to add your public local IP address.
Note: If you wish to allow all IP addresses, add "*". Wildcards are not accepted as a valid IP address, e.g. 161.18.23.*
2. If you wish to remove an IP address, just click on the icon next to it.
3. When you add/remove IP addresses from the list, click on the Save Configurations button otherwise these changes will not be saved. To confirm that everything was saved properly, click on the Get Data button to see the information that is currently in the database.
Allowed WebHook Domains
GPM's API has some resources that require longer processing time, and when sending a request to one of these EndPoints, part of the response will be an estimated response time. Users will have to provide an EndPoint where the results of the initial request will be posted after the stated response time.
In order to be able to use these resources, users will have to whitelist the domain of the EndPoints where the results of their requests will be posted later on.
1. To whitelist a domain, click on the Add Domain button on the Allowed WebHook Domains section >> A window with a simple text box and an Add button allows you to add all the domains that you need.
2. If you wish to remove a domain, just click on the icon next to it.
3. When you added/removed domains from the list, click on the Save Configurations button otherwise these changes will not be saved. To confirm that everything was saved properly, click on the Get Data button to see the information that is currently in the database.
Test Connection
After having granted API-specific privileges to a role, associated it to a system user and whitelisted IP addresses you can use the Test Connection button to test that you are able to authenticate properly.
Note: the IPs whitelisted list cannot be null, if you want to allow all IPs add "*" to the list and Save Configurations.
1. Click on the Test Connection button >> Select one of the system users that have a role with API Acccess associated to them >> Enter its password >> Click on Test Connection
2. If everything was properly configured, then a successful message should be displayed. Otherwise, an error message will show you why you were not able to authenticate.
Conclusion
This topic covered how to set up GPM's API in order to start accessing it. The API Configuration interface is the one place where you can find all the information you might need to authenticate and to provide API Access and specific privileges to a role and to a user. For more information on how to use each resource, please visit the API's documentation site
NZ- https://nzgpm.gensolve.com/api/.