API v2 Overview

When we released Issuetrak 14.9, we introduced a new API called API v2. This new API was designed to meet the OpenAPI standard, which makes developing integrations to work with Issuetrak easier than ever.

The purpose of this article is to assist you with getting started using API v2 specifically from the server side of things, which includes deployment, logging, rate limiting, and troubleshooting. For information about development-level interactions with API v2, please see https://api.issuetrak.com.

---

System Requirements

API v2 has the following requirements in addition to the usual requirements for Issuetrak itself:

• Communication with API v2 must be via a functional SSL binding
• Microsoft .NET 6.0 Hosting Bundle - which can be obtained here
• API v2 needs to be in its own IIS Application Pool, which must be set to "No Managed Code"

---

Deployment

API v2 can be deployed independently of the previous API, and uses its own application pool in IIS. The introduction of API v2 comes with slightly increased deployment complexity for customers that intend to install or upgrade their Issuetrak instance via the IDU.

Please see the following articles for assistance with deploying via the IDU:

• How to Install Issuetrak Using the Issuetrak Deployment Utility (IDU)
• How to Perform an Upgrade Using the Issuetrak Deployment Utility (IDU)

Additionally, some minor changes have been made to the IDM so that customers can install API v2, but these changes do not diverge significantly from installing the previous iteration of the API.

Please see the following articles for assistance with deploying via the IDM:

• How to Install Issuetrak Using the Issuetrak Deployment Manager (IDM)
• How to Perform an Upgrade Using the Issuetrak Deployment Manager (IDM)

---

Rate Limiting

API v2 uses rate limiting to protect the server against malicious or buggy clients. When requests exceed the configured rate limit, API v2 will return a "429 - Too Many Requests" response to the application attempting to access it.

Below is a table of the default rate limits:

Time Period	Default Rate Limit
1 second	20 requests
1 second POST/PUT/DELETE	5 requests
1 minute	100 requests
10 minutes	100 requests
1 hour	1000 requests
12 hours	1000 requests

Rate limits can be changed by editing the configuration file on the web server:

• {IssuetrakWebFolderPath}\api\v2\appsettings.json

We expect that minor changes to the existing limits is all that will be needed in most environments. Please see this page if you want to see detailed information on how the rate limiting can be configured.

---

Logging

Error logging is enabled by default, and all logs are accessible on the web server, and the level of logging can be adjusted by editing the appropriate configuration file. If you run into errors with your code when interacting with API v2, you will find that Trace IDs have been included in the API responses. You can search the server logs for the corresponding Trace ID to get detailed information about what went wrong.

• Error logging is enabled by default, and logs are stored in the {IssuetrakWebFolderPath}\api\v2\logs folder.
• Logging can be configured in the nlog.config file located in the {IssuetrakWebFolderPath}\api\v2 folder.
  • Changing the enabled="false" attribute on the <logger ... minlevel="Trace" ... /> line to enabled="true" will enable detailed logging.
• The API v2 app pool will need to be recycled for changes to take effect after you make changes to the nlog.config file.

---

Startup Logging

If you encounter a problem where the API v2 application will not start, you can turn on additional logging.

This is accomplished by editing the {IssuetrakWebFolderPath}\api\v2\web.config file, then changing the attribute stdoutLogEnabled on the <aspNetCore ...> element from "false" to "true". Enabling this logging will force the app pool to restart.

The logs are located in the {IssuetrakWebFolderPath}\api\v2\logs\stdout folder.

---

Troubleshooting

If you encounter trouble with API v2 not responding to requests at all, then you should take the following steps:

1. Open the {IssuetrakWebFolderPath}\api\v2\web.config file
   • Ensure that the "aspNetCore" tag has its argument set to .\Issuetrak.ApiV2.Site.Dll
   • Ensure that the environment variable "ASPNETCORE_ENVIRONMENT" is set to release
2. Verify {IssuetrakWebFolderPath}\api\v2\appsettings.json contains valid json
3. Verify {IssuetrakWebFolderPath}\api\v2\appsettings.release.json is valid json and looks like

{
  "ConnectionStrings": {
    "Issuetrak-Databse": "..."
  },
  "SecureStorageKeys": {
    "KeyForEncrypter-1": "..."
  },
  "SessionSigningKey": "..."
}

4. Enable the stdoutLogs in the {IssuetrakWebFolderPath}\api\v2\web.config and attempt a request. Review the log file for potential causes.

If you are still encountering difficulty, please contact Issuetrak Support for further assistance.