ApiCall

When (UID="$Alice.id") create todo, call table:
  | >todo1.id | title    |
  | <todoId   | Buy milk |

When (UID="$Alice.id") create todo, call JSON:
  """json
  {
    >todo1.id: <todoId,
    "title": "Buy milk"
  }
  """

# DataTable version
When (UID="$Alice.id") update todo, call table:
  | P:todoId  | Q:verbose | H:X-Trace | title        |
  | $todo1.id | true      | trace-123 | Buy soy milk |

# JSON version
When (UID="$Alice.id") update todo, call JSON:
  """json
  {
    P"todoId": $todo1.id,
    Q"verbose": "true",
    H"X-Trace": "trace-123",
    "title": "Buy soy milk"
  }
  """

| >todo1.id | >todo1.title | title    |
| <todoId   | <title       | Buy milk |

# DataTable — extract Location header
When (No Actor) create resource, call table:
  | >loc        | name          |
  | <H:Location | test resource |

# JSON — extract X-Request-Id header
When (No Actor) create resource, call JSON:
  """json
  {
    >requestId: <H"X-Request-Id",
    "name": "test resource"
  }
  """

When (No Actor) get resource status, call table:
  | >result | P:id  |
  | <B:     | $res1 |

# api-spec.yml (OpenAPI 3.0)
paths:
  /todos:
    post:
      summary: create todo    # ← ApiCall identifies by this summary
      operationId: createTodo
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - title
              properties:
                title:
                  type: string
                priority:
                  type: integer
      responses:
        "201":
          content:
            application/json:
              schema:
                type: object
                properties:
                  todoId:
                    type: integer
                  title:
                    type: string

# Corresponding Gherkin syntax
When (UID="$Alice.id") create todo, call table:
  | title    | priority |
  | Buy milk | 1        |

# ✅ Correct: summaries are distinct
/todos:
  post:
    summary: create todo
  get:
    summary: list todos

/todos/{id}:
  get:
    summary: get todo
  put:
    summary: update todo
  delete:
    summary: delete todo

# ❌ Wrong: duplicate summaries cause identification failure
/todos:
  get:
    summary: get todo
/todos/{id}:
  get:
    summary: get todo    # Duplicate!

# todoId is both Body and Path parameter → automatically routes to P:todoId
| todoId | title        |
| 123    | Buy soy milk |

# DataTable — use dot notation for nested structures
| name       | config.theme | tags[0] | tags[1] |
| My Project | dark         | work    | urgent  |

# JSON — describe nested structure directly
"""json
{
  "name": "My Project",
  "config": { "theme": "dark" },
  "tags": ["work", "urgent"]
}
"""

{
  "name": "My Project",
  "config": { "theme": "dark" },
  "tags": ["work", "urgent"]
}

# DataTable — use bracket notation
| content.["btn.save"] | content.["btn.cancel"] |
| Save                 | Cancel                 |

# JSON — keys naturally contain ".", framework handles escaping
"""json
{
  "content": {
    "btn.save": "Save",
    "btn.cancel": "Cancel"
  }
}
"""

data.[0].["field.name"]
→ data is an object key, [0] is an array index, ["field.name"] is an object key containing "."

When (No Actor) batch create todos, call JSON:
  """json
  [
    { "title": "Buy milk", "priority": 1 },
    { "title": "Write report", "priority": 2 }
  ]
  """

When (No Actor) batch create todos, call JSON:
  """json
  {
    P"projectId": $project1.id,
    Q"notify": "true",
    B: [
      { "title": "Buy milk", "priority": 1 },
      { "title": "Write report", "priority": 2 }
    ]
  }
  """

| P:projectId  | Q:notify | [0].title  | [0].priority | [1].title    | [1].priority |
| $project1.id | true     | Buy milk   | 1            | Write report | 2            |

# Implicit body (current syntax, backward-compatible)
"""json
{ P"projectId": $project1.id, "title": "Buy milk", "priority": 1 }
"""

# Explicit B: body (equivalent)
"""json
{
  P"projectId": $project1.id,
  B: { "title": "Buy milk", "priority": 1 }
}
"""

# DataTable — B: prefix carries bare value
When toggle resource status, call table:
  | P:id  | B:   |
  | $res1 | true |

# JSON — B: carries bare value
When (No Actor) toggle resource status, call JSON:
  """json
  { P"id": $res1, B: true }
  """

When (No Actor) submit feedback, call JSON:
  """json
  { B: "This is feedback" }
  """

# Use variable as caller
When (UID="$Alice.id") list todos, call table:
  | Q:status |
  | active   |

# No authentication required
When (No Actor) health check, call table:
  | |

Feature: Query API parameter validation

  Rule: Required parameter validation rules

    Example: Should succeed with complete parameters
      When (UID="$Alice.id") query data, call table:
        | Q:startDate | Q:endDate  | Q:pageNo | Q:pageSize |
        | 2024-01-01  | 2024-01-31 | 1        | 10         |
      Then query data(200) response, with table:
        | success |
        | true    |

    @allow-missing-parameters
    Example: Should fail when required parameter startDate is missing
      When (UID="$Alice.id") query data, call table:
        | Q:endDate  | Q:pageNo | Q:pageSize |
        | 2024-01-31 | 1        | 10         |
      Then query data(400) response, with table:
        | errorCode                  |
        | MISSING_REQUIRED_PARAMETER |

Feature: Todo Management

  Background:
    Given current time is "2026-01-27T10:00:00"

    # EntitySetup instruction — prepare test data (see EntitySetup docs)
    # >Alice.id / <userId: extract userId from response into Alice.id variable
    Given prepare a user, with table:
      | >Alice.id | name  | email             | status |
      | <userId   | Alice | alice@example.com | ACTIVE |

  Example: Create and update a todo

    # (No Actor): API call without authentication
    # >AliceToken / <token: extract token from response
    When (No Actor) user login, call table:
      | >AliceToken | email             | password    |
      | <token      | alice@example.com | password123 |

    # (UID="$Alice.id"): call as Alice, Bearer Token injected automatically
    When (UID="$Alice.id") create todo, call table:
      | >todo1.id | title    |
      | <todoId   | Buy milk |

    # P: prefix for Path parameter; $todo1.id references a previously extracted variable
    When (UID="$Alice.id") update todo, call table:
      | P:todoId  | title        |
      | $todo1.id | Buy soy milk |

    # ResponseValidate instruction — verify response (see ResponseValidate docs)
    Then update todo(200) response, with table:
      | todoId    | title        | updatedAt                        |
      | $todo1.id | Buy soy milk | &sameTime("2026-01-27T10:00:00") |