JSON API Responses

Demonstrates returning structured JSON from API handlers.

Example 043 of the basic Soma programs: a small, commented program that teaches one thing. Every output below was printed by soma 3.2.4 when this page was built.

How it is built

The cell JsonAPI has no face and no memory. Handlers: run (line 14).

Generated from soma describe on this file.

The source

043_json_api.cell

// ============================================================================
// 043 — JSON API Responses
// ============================================================================
// Demonstrates returning structured JSON from API handlers.
//
// Run:   soma run 043_json_api.cell run
// Expect:
//   Product: {"id": 1, "name": "Widget", "price": 9.99, "in_stock": true}
//   JSON: {"id": 1, "name": "Widget", "price": 9.99, "in_stock": true}
//   Catalog: [{"id": 1, "name": "Widget"}, {"id": 2, "name": "Gadget"}, {"id": 3, "name": "Doohickey"}]

cell JsonAPI {

    on run() {
        // Maps are automatically serialized as JSON when returned
        let product = map("id", 1, "name", "Widget", "price", 9.99, "in_stock", true)
        print("Product: {product}")

        // to_json explicitly converts to a JSON string
        let json = to_json(product)
        print("JSON: {json}")

        // Lists of maps become JSON arrays
        let catalog = list(
            map("id", 1, "name", "Widget"),
            map("id", 2, "name", "Gadget"),
            map("id", 3, "name", "Doohickey")
        )
        print("Catalog: {catalog}")

        return "done"
    }
}

What the toolchain says

$ soma check 043_json_api.cell
✓ All checks passed.

$ soma run 043_json_api.cell run
Product: {"id": 1, "name": "Widget", "price": 9.99, "in_stock": true}
JSON: {"id":1,"name":"Widget","price":9.99,"in_stock":true}
Catalog: [{"id": 1, "name": "Widget"}, {"id": 2, "name": "Gadget"}, {"id": 3, "name": "Doohickey"}]
done