Skip to content

Examples

These three directories are in samples/. Each one validates, and each one can be served with the command shown below. They listen on different ports so the curl lines work without extra flags.

Stop a server with Ctrl-C before you start the next one if you want the printed ports to stay free.

Hello API

samples/hello-api is a single file. It has a health route and a user route that turns the path id into a number.

version: 1

api:
  name: hello-api
  description: A small static API

server:
  host: 127.0.0.1
  port: 8080

management:
  host: 127.0.0.1
  port: 8081

routes:
  - id: health
    method: GET
    path: /health
    response:
      status: 200
      json:
        status: healthy

  - id: get-user
    method: GET
    path: /users/{id}
    response:
      status: 200
      json:
        id: "{{ path.id | int }}"
        name: Ada
ghostport validate samples/hello-api
ghostport serve samples/hello-api
curl -s http://127.0.0.1:8080/health
curl -s http://127.0.0.1:8080/users/7
{"status": "healthy"}
{"id": 7, "name": "Ada"}

A path that matches nothing returns 404:

curl -s -D - http://127.0.0.1:8080/missing -o /dev/null

The management status is on the other port:

curl -s http://127.0.0.1:8081/status

Task Board

samples/task-board splits routes, scenarios, and state across files. The root only names those files and the starting scenario.

version: 1

api:
  name: task-board
  description: A task board with stored records and a closed scenario

server:
  host: 127.0.0.1
  port: 8090

management:
  host: 127.0.0.1
  port: 8091

include:
  routes:
    - routes/tasks.yml
  scenarios:
    - scenarios/normal.yml
    - scenarios/closed.yml
  state:
    - state/tasks.yml

runtime:
  scenario: normal

The initial state is one board value and one task:

state:
  board:
    type: value
    value:
      open: true
  tasks:
    - id: "1"
      title: Write the guide
      done: false

The routes list, fetch, create, update, and delete tasks. They also read and replace the board value. Send JSON with Content-Type: application/json. A whole-value "{{ body }}" keeps the parsed object.

routes:
  - id: show-board
    method: GET
    path: /board
    action:
      type: state.get
      resource: board

  - id: set-board
    method: PUT
    path: /board
    action:
      type: state.set
      resource: board
      input: "{{ body }}"

  - id: list-tasks
    method: GET
    path: /tasks
    action:
      type: collection.list
      resource: tasks

  - id: get-task
    method: GET
    path: /tasks/{id}
    action:
      type: collection.get
      resource: tasks
      key: "{{ path.id }}"

  - id: create-task
    method: POST
    path: /tasks
    action:
      type: collection.create
      resource: tasks
      input: "{{ body }}"

  - id: update-task
    method: PATCH
    path: /tasks/{id}
    action:
      type: collection.update
      resource: tasks
      key: "{{ path.id }}"
      merge: true
      input: "{{ body }}"

  - id: delete-task
    method: DELETE
    path: /tasks/{id}
    action:
      type: collection.delete
      resource: tasks
      key: "{{ path.id }}"
ghostport validate samples/task-board
ghostport serve samples/task-board
curl -s http://127.0.0.1:8090/board
curl -s http://127.0.0.1:8090/tasks
curl -s -X POST http://127.0.0.1:8090/tasks \
  -H 'Content-Type: application/json' \
  -d '{"id":"2","title":"Review samples","done":false}'
curl -s http://127.0.0.1:8090/tasks/2
curl -s -X PATCH http://127.0.0.1:8090/tasks/2 \
  -H 'Content-Type: application/json' \
  -d '{"done":true}'
curl -s -X DELETE http://127.0.0.1:8090/tasks/1 -D -

Create returns 201 and the stored object. Update with merge: true keeps title and changes done. Delete returns 204 and an empty body.

The closed scenario replaces only list-tasks. Tasks you already created stay in state.

scenarios:
  - id: closed
    description: The board rejects task lists
    overrides:
      - route: list-tasks
        response:
          status: 503
          json:
            error: closed
ghostport scenario set closed --url http://127.0.0.1:8091
curl -s http://127.0.0.1:8090/tasks
curl -s http://127.0.0.1:8090/tasks/2
ghostport scenario reset --url http://127.0.0.1:8091
curl -s http://127.0.0.1:8090/tasks

While the scenario is closed, GET /tasks returns 503 and {"error":"closed"}. GET /tasks/2 still returns the record. scenario reset restores normal.

state reset puts the board back to the file's initial task and clears sequence counters. This sample has no sequences.

ghostport state show --url http://127.0.0.1:8091
ghostport state reset --url http://127.0.0.1:8091

Checkout

samples/checkout is the largest sample. The catalogue is a fixture file. Orders live in SQLite. Payments follow a three-step sequence, and only when the request has x-shop: demo. An audit route is configured to fail before it writes state.

version: 1

api:
  name: checkout
  description: Catalogue fixtures, a payment sequence, and SQLite orders

server:
  host: 127.0.0.1
  port: 8100

management:
  host: 127.0.0.1
  port: 8101

include:
  routes:
    - routes/catalogue.yml
    - routes/payments.yml
  state:
    - state/orders.yml

runtime:
  scenario: normal
  state:
    persistence: sqlite
    path: .ghostport/state.sqlite
  history:
    enabled: true
    max_entries: 1000
    capture_bodies: true
    max_body_bytes: 65536
    redact_fields:
      - card
  unmatched:
    status: 404
    json:
      error: No checkout route matched
  behaviour:
    default_delay_ms: 0
    random_seed: 12345
ghostport validate samples/checkout
ghostport serve samples/checkout

The catalogue response is the fixture bytes:

curl -s http://127.0.0.1:8100/catalogue
{
  "items": [
    {"sku": "mug", "name": "Blue mug", "price": 12},
    {"sku": "poster", "name": "Harbour poster", "price": 18}
  ]
}

Place an order. The body must be a JSON object and must include id.

curl -s -X POST http://127.0.0.1:8100/orders \
  -H 'Content-Type: application/json' \
  -d '{"id":"101","sku":"poster","qty":2}'
curl -s http://127.0.0.1:8100/orders

Stop the server and start it again. GET /orders still lists order 101, because the SQLite file is samples/checkout/.ghostport/state.sqlite. Delete that file, or call ghostport state reset --url http://127.0.0.1:8101, to restore the order seeded in state/orders.yml.

The payment sequence is 503, then 200, then 410.

routes:
  - id: take-payment
    method: POST
    path: /payments
    match:
      headers:
        x-shop: demo
    after_sequence: error
    exhaustion:
      status: 410
      json:
        error: Sequence exhausted
    sequence:
      - status: 503
        json:
          error: busy
      - status: 200
        json:
          paid: true

  - id: record-audit
    method: POST
    path: /audit
    behaviour:
      failure_status: 503
    action:
      type: collection.create
      resource: audits
      input: "{{ body }}"
curl -s -X POST http://127.0.0.1:8100/payments \
  -H 'Content-Type: application/json' \
  -H 'x-shop: demo' \
  -d '{}'
curl -s -X POST http://127.0.0.1:8100/payments \
  -H 'Content-Type: application/json' \
  -H 'x-shop: demo' \
  -d '{}'
curl -s -X POST http://127.0.0.1:8100/payments \
  -H 'Content-Type: application/json' \
  -H 'x-shop: demo' \
  -d '{}'
{"error": "busy"}
{"paid": true}
{"error": "Sequence exhausted"}

The same post without x-shop: demo does not match the route:

curl -s -D - -X POST http://127.0.0.1:8100/payments \
  -H 'Content-Type: application/json' \
  -d '{}'

That response is 404 and {"error":"No checkout route matched"}.

Reset the sequence without touching orders:

ghostport sequence reset take-payment --url http://127.0.0.1:8101

The next payment request is 503 again.

POST /audit is an action with failure_status: 503. The action does not run, so the empty audits collection stays empty.

curl -s -D - -X POST http://127.0.0.1:8100/audit \
  -H 'Content-Type: application/json' \
  -d '{"id":"9","card":"4242"}'
ghostport state show --url http://127.0.0.1:8101

History keeps the request and stores the card field as [redacted].

ghostport history list --url http://127.0.0.1:8101
ghostport history show REQUEST_ID --url http://127.0.0.1:8101

Replace REQUEST_ID with an id from the list. random_seed in this project is stored with the configuration. It does not change any response.