The public REST API for the iGrafx Platform allows you to interact with the application in an automated fashion. It was introduced with the iGrafx Platform version 16.2 and coverage has been and will continue to be improved over time on request.
The REST API can use either basic authentication or an API key to authenticate users. If using basic authentication be aware that login names and passwords are sent across the network unencrypted. If using an API key that key is sent unencrypted, but passwords cannot be recovered from that key. Malicious users can intercept this information. You can use Basic authentication and still protect account information by enabling SSL (HTTPS) encryption for this iGrafx Platform.
This warning will also appear on the REST API page if your server uses unencrypted HTTP.
Enabling the API
By default the API is disabled. To enable it, follow these steps:
- Open the iGrafx Platform using an admin account.
- Go to Administration > Support > REST API
- The API is disabled by default, enable it if you plan to test or use it.
- Determine whether you will use basic authentication, API keys, or both and enable appropriately.
Accessing API documentation
Minimum permissions for a user to access the REST API documentation is a Server Role including Access Support Features.
The extent of the REST API depends on the exact version of the iGrafx Platform application server, and the documentation for the REST API is contained within the application.
A link to the API documentation can be found on the REST API page as shown below. You can bookmark this link to make it easier to access.
Accessing the API
The REST API validates the permissions and licenses of the user accessing the API end point. It is recommended to create a dedicated API user with permissions and licenses limited to your use case.
To successfully access an API endpoint:
- The API must be enabled as shown above
- The user that the supplied credentials identifies must have the server permission to access the API
- The user must be licensed for the activity that the endpoint uses
- The user must have repository and/or server permission to do the operation the endpoint supports
Getting your API Key
As an administrator account (With the API enabled):
- Administrator → User Management
- Find the user who needs an API Key
- Click either their name or the edit button.
- Scroll down and select Generate API Key.
Ways to use the API key
Using an API Key in the request header
After getting your API Key you would need to set the value of "X-AUTH-APIKEY:" to the the API Key value you got from the Getting your API Key.
A request header is used so that the user's browser sends information to a web server containing the details of what the user's browser wants / will accept back the server. We can add our request header here containing the API Key.
Using an API Key as a Query Param
After getting your API Key you would need to set the value of "?apiKey=" to the the API Key value you got from the Getting your API Key.
A query String is used to assign values to specified parameters. In this case the parameter is apiKey and it would be assigned the value "YOUR_KEY_HERE".
You can have more than one query param and the order doesn't matter. They should be separated by an '&'.
The follow example would produce the same result.