Review API Gateway path segments

Changing a path changes the URL that clients use.

Match the finding

These titles and messages come from this local checker. They are not AWS service error quotes.

Path needs manual review
API Gateway REST path segments use a restricted character set. Parameters must occupy a full segment; a greedy {proxy+} parameter is supported only as the final segment. No path is renamed automatically.

Cause and scope

API Gateway REST restricts path-segment characters and requires parameters to occupy a whole segment. This checker accepts a greedy {proxy+} parameter only as the final segment.

What to do

Review the reported route against the intended public URL and AWS resource layout. If a URL must change, update parameter definitions, integration mappings, clients, and tests together.

Check that each parameter is a complete segment, such as /pets/{petId}.
Check restricted characters and place {proxy+}, if used, only at the end.
Review any route change with API consumers and test request routing after import.

Path fragment: place a parameter in its own segment

# /pets{petId} would trigger a path warning.
paths:
  /pets/{petId}:
    parameters:
      - name: petId
        in: path
        required: true
        schema:
          type: string
    get:
      responses:
        '200':
          description: A pet

The parameter name matches the placeholder and is required. Replacing /pets{petId} with /pets/{petId} changes the URL, so use this layout only after reviewing client and integration changes; the checker never renames routes.

Avoid a misleading fix

Do not silently remove characters or rename routes to make import pass. A syntactically accepted path can still be a breaking API change.

Check your complete file locally

Choose one OpenAPI 3.0 JSON or YAML file, diagnose the findings, and review any eligible security-copy preview before downloading. No file upload or account is needed.

Open the free OpenAPI checker →

Related findings

Sources and scope

Scope: this local checker, API Gateway REST APIs, and OpenAPI 3.0. Guidance reviewed 4 October 2026. A passing check does not guarantee import or runtime behavior.