Migration Guide: ThousandEyes API v6 to v7

Introduction

Welcome to the migration guide for transitioning from version 6 to version 7 of the ThousandEyes API. This guide is intended to help developers and system integrators upgrade their integrations seamlessly to the latest API version. Since this is a major version upgrade, there are significant changes to API endpoints, including modifications to:

  • HTTP Methods
  • Endpoint Paths
  • Request and Response Bodies
  • Overall API Behavior

This guide ensures you fully understand these changes, enabling a smooth and efficient migration.

What to Expect

The guide provides:

  • Endpoint-by-endpoint comparisons between version 6 and version 7.
  • Detailed descriptions of changes in HTTP methods, paths, and data structures.
  • Explanations of new features and improvements in version 7.

Endpoints are grouped based on categories from the API v6 documentation to maintain familiarity. For example, the “Get Usage Quotas” endpoint in version 6 is documented under “Administrative Endpoints,” while its corresponding v7 endpoint is documented under the “Usage” section of the developer reference. In this guide, you will find both these endpoints in the “Administrative Endpoints” section.

By following this guide, you can confidently update your applications to benefit from the new features and improvements in version 7, ensuring continued functionality and enhanced performance.

General Changes in API v7

Before diving into specific endpoints, it’s essential to understand the overarching changes in version 7. These improvements are designed to enhance consistency, security, and data handling across the API.

  1. Response Format:

    • v6: Supported both JSON and XML responses (e.g., appending .json or .xml to the URL path).
    • v7: Supports only JSON responses. Appending .json or .xml to URLs will result in a 404 error.

  2. Authentication:

    • v6: Supported both HTTP Basic Authentication and Bearer Token Authentication.
    • v7: Exclusively uses Bearer Token Authentication. HTTP Basic Authentication is no longer supported.

  3. Resource Expansion:

    • New expand query parameter allows related data to be included in responses.
    • If related data seems missing in v7, check for the expand parameter to include additional resources.

  4. Data Structure Updates:

    • Object Identifiers: Changed from integers to strings for consistency.
    • Boolean Values: Switched from 0 or 1 to true or false.

  5. Data Format Updates:

    • Timestamps: Now use the ISO 8601 format (2024-02-07T15:20:21Z) instead of the previous format (2024-02-07 15:20:21).

  6. URL Versioning:

    • v7: Mandates explicit versioning in the URL path (e.g., https://api.thousandeyes.com/v7/...).
    • v6: Supported unversioned requests, which are no longer allowed.

  7. Pagination Enhancements:

    • v6: Used a pages key for paginated results.
    • v7: Incorporates pagination within the _links key, aligning with the HATEOAS principle for standardized resource navigation.

Next Steps

With these general changes in mind, proceed to the endpoint-by-endpoint details, where you’ll find:

  • Comparisons of HTTP methods, paths, and data structures.
  • Highlights of key differences between v6 and v7.

By understanding these foundational changes and following the detailed instructions in this guide, you can ensure a seamless migration to ThousandEyes API v7.