Say hello to Issuetrak API v2

We’re excited to announce that Issuetrak 14.9 features API v2! Our new API v2 adheres to the OpenAPI specification, a standard for developing APIs maintained by the OpenAPI Initiative, which was founded by industry giants such as the Linux Foundation, Microsoft, IBM, and Google. 

API v2 offers a lot of benefits, starting with easier integration with third-party apps that support the OpenAPI specification. This will also make it easier to find the right API client-generating tools to write code using API v2.

Read on for more advantages offered by our new release.

In this article

• Issuetrak API v2 is based on the OpenAPI industry standard, providing easier integration with other third-party apps that support the standard.
• API v2 streamlines and simplifies authentication in new and exciting ways, like:
  • You can create and revoke API authentication tokens directly within Issuetrak.
  • Because the tokens are associated with specific users, they only allow the API to complete actions those users can perform.
• The API provides the same underlying functionality as the Issuetrak application, making it easier to code.
• API v2 allows customers to search and retrieve entities using entity-based fields, where the previous API only allowed searching on issues. 
• Detailed error codes and messages, as well as trace IDs in logging, make troubleshooting any mishaps much easier.
• New and interactive documentation using Swagger is available within the product or publicly accessible at api.issuetrak.com.

Simplified authentication

What’s changed: Authentication is performed through the creation of an API token that grants access to the API as a specific Issuetrak user. API tokens can be generated within an Issuetrak site by Sys Admins or users who have been granted permission to access Issuetrak API v2. The API token can then be used to authenticate each request to the API.

The previous API required the creation of an API key using an external application. For each request to the API, the caller had to generate a Request ID — a specifically formatted timestamp, which didn’t allow much variation between the server and the caller's computer time — and encrypt and encode those with additional information from the request, then include that encoded string in the header of the request. 

New: API key token generation

With the new API v2, an API token is generated once (with an optional expiration date), and can then be used for any number of API requests. This follows modern industry best practices for APIs, and offers an improvement over the previous API. 

Now, the only thing a user needs to access Issuetrak API v2 is an API token, which can be generated within Issuetrak itself. No external applications or code are needed to generate this API token. This makes for a streamlined experience for the user calling the API. The user logs into the Issuetrak website; navigates to the “API v2 Tokens” page; creates a new API token for their intended usage of the API (e.g. integrating with a chat client); copies the generated API token (it will only be displayed to the user once, so keep it someplace secure); and then uses that API token with requests they make to the API v2.

Each user has their own API tokens that they create themselves or that a Sys Admin has created for them. All actions performed by API requests made with a given API token are performed as the user that owns that API token and are governed by that user's permissions within the Issuetrak product.

New: Per-user authentication

Using the new API v2, the actions performed by each API request are processed as a specific Issuetrak user, determined by the API token used for the request. The API request can only perform actions that the user has permission to perform. This allows for much more secure and controlled API usage than the previous API, which only performed actions as a user with all permissions.

Consistent application functionality

Issuetrak API v2 provides the same underlying functionality as the Issuetrak application, making it easier to code.

API v2 was designed from the ground up to use the same underlying functionality Issuetrak sites use. This means that if an action performed by a given user through their Issuetrak site has a specific behavior, then performing that same action through the API v2 using an API token belonging to that user should exhibit the same behavior. 

A more specific example: If Susan logs into the website and edits a user's profile, a Profile Change notification will be sent out. If Susan uses an API token she created (or that a Sys Admin created for her) to make a request to the /api/v2/users/{iid} update endpoint using her API token, a Profile Change notification will also be sent out.

Enhanced searching

Most entities (such as users and groups) that can be retrieved through the new API v2 can be searched using filters. The previous API only allowed searching on issues. With the new API v2, searches can be performed to retrieve entities based on the values in any number of fields. 

Here’s an example. A filter containing criteria for each field to be searched on is passed to an API v2 search endpoint (such as /api/v2/users/search). Each criterion can specify its type ("MatchAny", "Contains", etc.) and an optional list of values. An example of a filter for a user is:

{

  firstName: { type: "MatchAny", values: ["Susan", "John", "Amy"] },

  isActive: { type: "IsTrue" }

 }

Easier troubleshooting

The new API v2 is designed to be easy and simple to use. But sometimes things can still go wrong when making an API request. Happily, API v2 makes troubleshooting easier, too.

When a request isn’t successful, the user receives an HTTP status code and error messages that explain what went wrong. For example: 

• An HTTP status code of 401 - Unauthorized means that the API token is either missing, expired, or invalid.
• An HTTP status code of 404 - Not Found means the resource the user requested could not be found.
• An HTTP status code of 400 - Bad Request means that something was wrong with the data the user sent with the request. This code will also return one or more messages explaining what was wrong, like “‘Last Name’ must not be empty,” or “'Email' is not a valid email address.”

In addition, every response from any API v2 request will include a trace ID unique to that request, which will always be included in any log entries generated during the API request. This makes it very simple to find log entries for a specific API request, which makes troubleshooting API v2 problems easier.

The detailed error codes and messages and the trace ID make troubleshooting what went wrong with an API request much easier. API v2 not only lets the user know that something went wrong, but specifies exactly what went wrong, and makes it easy to locate any additional logs for that API request. 

Improved documentation

New and interactive documentation using Swagger is available within the product or publicly accessible at api.issuetrak.com. While we used Swagger as a testing platform before, its deployment was a little disjointed with the previous API. Now, our documentation is available within Swagger, right alongside the testing environment. We’ve also made this documentation available to the public via our website for the first time!

We’re thrilled to make this offering and would love to hear what you think. Questions? Comments? Join our Issuetrak Insiders User Network on LinkedIn, or find us on Reddit.