Creating API Scenarios

An API scenario is a sequence of HTTP requests with assertions, variable extraction, and authentication. Think of it as a test case for your API.

Basic Scenario

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  $CSS_URL/api/scenarios \
  -d '{
    "name": "User CRUD Lifecycle",
    "projectId": 1,
    "environmentId": 1,
    "baseUrl": "{{baseUrl}}",
    "steps": [
      {
        "stepOrder": 1,
        "name": "Create user",
        "httpMethod": "POST",
        "endpointPath": "/api/users",
        "requestBody": "{\"name\":\"John\",\"email\":\"john@example.com\"}",
        "expectedStatusCodes": [201],
        "extractions": [
          {
            "variableName": "userId",
            "extractionType": "JSONPATH",
            "extractionExpression": "$.id",
            "isRequired": true
          }
        ]
      },
      {
        "stepOrder": 2,
        "name": "Read user",
        "httpMethod": "GET",
        "endpointPath": "/api/users/{{userId}}",
        "expectedStatusCodes": [200],
        "responseAssertions": [
          {
            "type": "JSONPATH",
            "expression": "$.name",
            "operator": "EQUALS",
            "expectedValue": "John"
          }
        ]
      },
      {
        "stepOrder": 3,
        "name": "Delete user",
        "httpMethod": "DELETE",
        "endpointPath": "/api/users/{{userId}}",
        "expectedStatusCodes": [200, 204]
      }
    ]
  }'

Key Concepts

Variable Extraction

Extract values from responses and use them in later steps:

"extractions": [
  {
    "variableName": "userId",
    "extractionType": "JSONPATH",
    "extractionExpression": "$.id"
  }
]

Reference with {{userId}} in subsequent steps — URLs, headers, bodies.

Assertions

Validate responses:

"responseAssertions": [
  {"type": "JSONPATH", "expression": "$.status", "operator": "EQUALS", "expectedValue": "active"},
  {"type": "JSONPATH", "expression": "$.items", "operator": "EXISTS", "expectedValue": ""},
  {"type": "JSONPATH", "expression": "$.count", "operator": "GREATER_THAN", "expectedValue": "0"}
]

Operators: EQUALS, NOT_EQUALS, CONTAINS, EXISTS, NOT_EXISTS, GREATER_THAN, LESS_THAN

Authentication

Proofarc supports 5 authentication types:

Type	Use Case
Bearer (login endpoint)	Most REST APIs — auto-fetches token via login
OAuth2 Client Credentials	Enterprise APIs, Auth0, Okta
Static Bearer Token	CI/CD pipelines, service accounts
Basic Auth	Legacy APIs
API Key	Public APIs with rate limiting

Example — Bearer with login endpoint:

"authConfig": {
  "authType": "BEARER",
  "tokenSource": "LOGIN_ENDPOINT",
  "loginEndpoint": "/auth/login",
  "tokenJsonPath": "$.accessToken",
  "credentials": {
    "username": "admin",
    "password": "your-password"
  }
}

YAML Format

Prefer writing scenarios in YAML? The same scenario can be written as:

name: User CRUD Lifecycle
baseUrl: "{{baseUrl}}"
steps:
  - name: Create user
    method: POST
    path: /api/users
    body:
      name: John
      email: john@example.com
    expect: [201]
    extract:
      userId: $.id
  - name: Read user
    method: GET
    path: /api/users/{{userId}}
    expect: [200]
    assert:
      - path: $.name
        equals: John
  - name: Delete user
    method: DELETE
    path: /api/users/{{userId}}
    expect: [200, 204]

Create via API: POST /api/scenarios/yaml?projectId=1&environmentId=1

See YAML Format for full reference and editor usage.

Editing Steps in the UI

Open an existing scenario and click Edit to manage its steps directly:

• Add Step — the button at the top of the Steps section appends a new step (defaults to GET /); expand it to fill in the method, path, expected status codes, headers, body, and extractions, then click Save Step.
• Edit — expand any step to change its fields inline and Save Step.
• Reorder — use the up/down arrows on each step.
• Delete — remove a step with the trash icon.

You can also import steps from a Swagger/OpenAPI spec via the Scenario Wizard.

What Happens Next

Your API scenario is a test case. From here it can:

1. Execute → Run against any environment, get pass/fail per step
2. Convert to Performance Test → Same endpoints, same auth, now with concurrent users
3. Feed the Readiness Score → Pass rate contributes to your 0-100 score
4. Map to Compliance → Test execution evidence auto-maps to SOC 2, PCI-DSS controls