Migrating to Standardized OpenAPI Operation IDs

As part of our commitment to improving our developer experience and tooling, JumpCloud is updating its API documentation pipeline to standardize how operationId fields are generated across our OpenAPI specifications.

This article explains what is changing, how it might affect your automated workflows or SDKs, and how you can use our migration mapping file to transition smoothly.

What is Changing?#

We are moving away from legacy, manually managed Operation IDs to a programmatic, codegen-style naming convention. In our new specification bundles (to be published on the https://docs.jumpcloud.com/new page), every API endpoint will have its operationId automatically derived from its HTTP Method and its Host-Root Path.

• The Legacy Format: Historically, operation IDs used a mix of camelCase and snakecase format, such as groups_system_list.
• The Standardized Format: The new format uses a deterministic camelCase structure, transforming the previous example into getApiV2Systemgroups.

NOTE: Our legacy documentation (https://docs.jumpcloud.com/) will continue to serve the older upstream Operation IDs until the official final cutover date, giving your engineering teams ample time to test and adapt.

What is Not Changing?#

• HTTP methods and paths (e.g. GET /api/v2/systemgroups)
• Request and response payloads
• Authentication, headers, and query parameters
• Runtime API behavior

How This Impacts You#

If you interact with JumpCloud APIs purely through standard HTTP requests, this change won’t impact you.
However, if your development team uses automated tools (such as OpenAPI Generator or AutoRest) to automatically generate SDKs, API clients, or wrapper libraries, this update will change the names of the methods generated by your code.
For example, a generated code snippet that previously called a legacy method name will now map to a new, standardized method name:

Migration Support#

To help you migrate your downstream SDKs and software development lifecycles, our docs pipeline now publishes a machine-readable sidecar mapping file alongside each aggregated documentation bundle. The mapping files will be published separately for both JumpCloud Console API and Directory Insights API separately.

• JumpCloud Console APIs
• Directory Insights APIs

This YAML schema provides an explicit bridge between old and new identifiers, featuring five key attributes per entry to help you programmatically script your internal updates:

1. method (The HTTP Verb)
2. host_root_path
3. base_path
4. legacy_operation_id
5. standardized_operation_id

The Mapping Structure#

The sidecar file structure looks like this:

# operation-id-mapping.yaml snippet
- method: "GET"
  host_root_path: "api/v2"
  base_path: "/systemgroups"
  legacy_operation_id: "groups_system_list"
  standardized_operation_id: "getApiV2Systemgroups"

To help you understand the change, let’s look at the “list system groups” operation as an example.

Important

The code samples in this guide are illustrative examples only, not implementation requirements. Your migration approach may vary based on your SDK, codegen tooling, and internal automation. Use the published operation ID mapping files as the authoritative reference when updating legacy operation IDs on your side.

While the API call remains the same, only the identifier changes.

In the OpenAPI spec file, you’ll see the following change:

# Before
paths:
 /api/v2/systemgroups:
   get:
     operationId: groups_system_list


# After
paths:
 /api/v2/systemgroups:
   get:
     operationId: getApiV2Systemgroups

OpenAPI Generated Client#

Many teams generate a client from our OpenAPI specifications. The method names are derived from each operation’s operationId. After we publish the new specs, regenerating the client will produce new method names (as shown below).
This is not a runtime change to the API itself. You will need to regenerate your client and update your code if it references the old method names.

# Before — method name came from legacy operationId
system_groups = client.groups_system_list()

# After — same HTTP call, new method name
system_groups = client.get_api_v2_systemgroups()

Custom Operation Based on operationId#

If your automation stores JumpCloud API actions by name (for example in config files, test suites, or internal wrappers) and those names come from the OpenAPI operationId, you will need to update them to match the new standardized names.

# Before
OPERATIONS = {
    "groups_system_list": {
        "method": "GET",
        "path": "/api/v2/systemgroups",
    },
}

# After
OPERATIONS = {
    "getApiV2Systemgroups": {
        "method": "GET",
        "path": "/api/v2/systemgroups",
    },
}

# Before
def run(client, operation_id, **kwargs):
    if operation_id == "groups_system_list":
        return client.get("/api/v2/systemgroups", **kwargs)

run(client, "groups_system_list")

# After
def run(client, operation_id, **kwargs):
    if operation_id == "getApiV2Systemgroups":
        return client.get("/api/v2/systemgroups", **kwargs)

run(client, "getApiV2Systemgroups")

For a Direct HTTP request, you won’t see any change.

# Unchanged — operationId is not used in direct HTTP calls
import requests

response = requests.get(
    "https://console.jumpcloud.com/api/v2/systemgroups",
    headers={"x-api-key": API_KEY},
)