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
A path that matches nothing returns 404:
The management status is on the other port:
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:
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 }}"
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.
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
The catalogue response is the fixture bytes:
{
"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 '{}'
The same post without x-shop: demo does not match the route:
That response is 404 and {"error":"No checkout route matched"}.
Reset the sequence without touching orders:
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.