Guide

API

Overview.

In the world of Automate Everything, it is not just a nice to have thing but a requirement to expose broad and well-defined API.
Here, at Perforator, we follow an API-first approach.
So, all the functionality of our platform, like WEB-UI and multiple performance testing integrations - everything is powered by the same API.

Our API is defined in "Open API Specification" (formerly Swagger) format, and you can access it as both YAML and JSON:
- https://api.perforator.io/oas.yml
- https://api.perforator.io/oas.json
We have integrated swagger-ui, so you can start playing with it directly from your browser: https://api.perforator.io/swagger-ui/

Security.

Access to Perforator API requires all API calls to be authorized, meaning that you should register first on the platform and get your unique credentials. Thus, secured API access is divided into two standalone phases: authentication and authorization.

During the authentication phase, you need to provide your own set of client_id / client_secret and exchange it to the JWT access token using OAuth 2.0 Client Credentials Grant flow. Please keep in mind that client_id and client_secret are not the same as your login/password to access the web application.

Please open the "Settings / API" page to get your API credentials.

API Client ID identifies your organization, so all users within the same organization share the same id - such key can be easily shared with your colleagues and doesn't require a secure vault for storage.

API Client Secret is your security key to confirm that you are really you during API authentication calls. You can create multiple secret keys according to your requirements or projects need. Please keep it in a secret and safe place since anybody who knows your secret key can act on your behalf. The general rule is to treat the secret key the same way as your password. We store it in a hashed and salted way without keeping its plain text value on our servers. As a result, your secret key is only displayed once at the time of its generation, and can't be revealed again.

Note: Please copy the secret key value and store it securely every time you create one. Due to security reasons, we do not store secrets in plain text. As a result, neither you nor anybody else can restore the value once dialog is closed.

Once you have your client id and secret, the second step is to exchange such keys to get an access token. An access token is required to be present during all API calls. Please take a look at the command line example below describing how to get a JWT access token and submit an API call.


Prebuilt API Client.

All integrations with the Perforator platform are open-sourced.
Please take a look at our GitLab repository "Perforator SDK Java" if you are interested in what we have released so far.
You can find the source code for the client at the api-okhttp-gson module.

1. Download and unarchive prebuilt examples.
2. Start editing com.example.projects.ListProjectsExample class using your favorite IDE.
3. Update apiClientId property with your own value. Please navigate to the API Settings page to get your API Client ID.
4. Update apiClientSecret property with your own value. Please navigate to the API Settings page to get your API Client Secret.
5. Build example project using maven, for example `mvn clean compile`
6. Run com.example.projects.ListProjectsExample class.

Note: Please make sure that JDK 11+ and Maven 3 is installed on your computer and available in your terminal PATH.
Execute `mvn --version` in your terminal to validate both.

OpenAPI Generator.

Open API Specification format allows automatic API client code generation for all major programming languages.
For example, all Perforator-based load generators utilize autogenerated API client.

For sure, you can implement your own API client to our platform via manually writing the code and following this documentation.
Still, we strongly encourage you against doing so because it is a very error-prone and time-consuming process.
It is much easier to utilize tools like OpenAPI Generator and automatically generate source code for API client.