json api

Author: matt-beanland

.claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mix deps.get)",
+      "Bash(git -C /Users/beanlanda/git/diffo_example status)",
+      "Read(//Users/beanlanda/git/**)",
+      "Read(//Users/beanlanda/.mix/**)"
+    ]
+  }
+}

CHANGELOG.md

@@ -37,6 +37,4 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline
 * updated to diffo 0.2.0
 
 ### Features:
-* new NBN domain modelling NBN Ethernet access and constituent resources (UNI, AVC, NTD, CVC, NNI Group, NNI)
-* NBN Technology and Speeds as Ash Enum types
-* speeds derived from NTD technology and AVC bandwidth_profile via mine action
+* new NBN domain modelling NBN Ethernet access and constituent resources (UNI, AVC, NTD, CVC, NNI Group, NNI), JSON API and livebook

config/config.exs

@@ -16,6 +16,7 @@ config :spark,
         :characteristics,
         :neo4j,
         :jason,
+        :json_api,
         :outstanding,
         :actions,
         :state_machine,

diffo_example.livemd

@@ -9,7 +9,21 @@ SPDX-License-Identifier: MIT
 ```elixir
 Mix.install(
   [
-    {:diffo_example, "~> 0.2.0"}
+    {:diffo_example, "~> 0.2.0"},
+    {:req, "~> 0.5"}
+  ],
+    config: [
+    bolty: [{Bolt, [
+      uri: "bolt://localhost:7687",
+      auth: [username: "neo4j", password: "password"],
+      user_agent: "diffoExampleLivebook/1",
+      pool_size: 15,
+      max_overflow: 3,
+      prefix: :default,
+      name: Bolt,
+      log: false,
+      log_hex: false
+    ]}]
   ],
   consolidate_protocols: false
 )
@@ -37,25 +51,9 @@ The NBN domain models a fictional NBN Ethernet access circuit and its constituen
 
 ## Installing Neo4j and Configuring Bolty
 
-Update the configuration below to match your Neo4j installation and evaluate.
+Bolty is configured in the `Mix.install` block above — update the Neo4j credentials there if needed before evaluating.
 
-```elixir
-config = [
-  uri: "bolt://localhost:7687",
-  auth: [username: "neo4j", password: "password"],
-  user_agent: "diffoExampleLivebook/1",
-  pool_size: 15,
-  max_overflow: 3,
-  prefix: :default,
-  name: Bolt,
-  log: false,
-  log_hex: false
-]
-```
-
-```elixir
-AshNeo4j.BoltyHelper.start(config)
-```
+You need [Neo4j](https://neo4j.com/deployment-center/) installed and running. Verify the connection:
 
 ```elixir
 AshNeo4j.BoltyHelper.is_connected()
@@ -148,11 +146,11 @@ nni_group |> Jason.encode!(pretty: true) |> IO.puts
 Define the NNI Group with an SVLAN assignment and relate the NNI:
 
 ```elixir
-nni_group = Nbn.define_nni_group!(%{
+nni_group = Nbn.define_nni_group!(nni_group, %{
   characteristic_value_updates: [nni_group: [svlan: 100]]
 })
 nni_group = Nbn.relate_nni_group!(nni_group, %{
-  relationships: [%{alias: :nni, target_id: nni.id, type: :isAssigned}]
+  relationships: [%Diffo.Provider.Instance.Relationship{id: nni.id, alias: :nni, type: :isAssigned}]
 })
 nni_group |> Jason.encode!(pretty: true) |> IO.puts
 ```
@@ -162,7 +160,7 @@ Build a CVC — the aggregation virtual circuit that terminates at the NNI Group
 ```elixir
 cvc = Nbn.build_cvc!(%{})
 cvc = Nbn.relate_cvc!(cvc, %{
-  relationships: [%{alias: :nni_group, target_id: nni_group.id, type: :isAssigned}]
+  relationships: [%Diffo.Provider.Instance.Relationship{id: nni_group.id, alias: :nni_group, type: :isAssigned}]
 })
 cvc |> Jason.encode!(pretty: true) |> IO.puts
 ```
@@ -187,7 +185,7 @@ Build a UNI — the interface at the customer premises — and assign a port fro
 uni = Nbn.build_uni!(%{})
 alias Diffo.Provider.Assignment
 ntd = Nbn.assign_port!(ntd, %{
-  assignment: %Assignment{assignee_id: uni.id, value: 1}
+  assignment: %Assignment{assignee_id: uni.id, operation: :auto_assign}
 })
 ntd |> Jason.encode!(pretty: true) |> IO.puts
 ```
@@ -196,7 +194,7 @@ Relate the UNI back to the NTD so it can mine technology and port from it:
 
 ```elixir
 uni = Nbn.relate_uni!(uni, %{
-  relationships: [%{alias: :ntd, target_id: ntd.id, type: :isAssigned}]
+  relationships: [%Diffo.Provider.Instance.Relationship{id: ntd.id, alias: :ntd, type: :isAssigned}]
 })
 uni = Nbn.mine_uni!(uni, %{})
 uni |> Jason.encode!(pretty: true) |> IO.puts
@@ -210,7 +208,7 @@ avc = Nbn.define_avc!(avc, %{
   characteristic_value_updates: [avc: [bandwidth_profile: :home_ultrafast]]
 })
 cvc = Nbn.assign_cvlan!(cvc, %{
-  assignment: %Assignment{assignee_id: avc.id, value: 200}
+  assignment: %Assignment{assignee_id: avc.id, operation: :auto_assign}
 })
 avc = Nbn.mine_avc!(avc, %{})
 avc |> Jason.encode!(pretty: true) |> IO.puts
@@ -222,8 +220,8 @@ Now build the top-level NBN Ethernet access and relate it to both the UNI and AV
 pri = Nbn.build_nbn_ethernet!(%{})
 pri = Nbn.relate_nbn_ethernet!(pri, %{
   relationships: [
-    %{alias: :uni, target_id: uni.id, type: :isAssigned},
-    %{alias: :avc, target_id: avc.id, type: :isAssigned}
+    %Diffo.Provider.Instance.Relationship{id: uni.id, alias: :uni, type: :isAssigned},
+    %Diffo.Provider.Instance.Relationship{id: avc.id, alias: :avc, type: :isAssigned}
   ]
 })
 pri = Nbn.mine_nbn_ethernet!(pri, %{})
@@ -246,6 +244,28 @@ Or from Elixir:
 AshNeo4j.Cypher.run("MATCH (n1)-[r]->(n2) RETURN r, n1, n2 LIMIT 50")
 ```
 
+## JSON API
+
+The NBN domain exposes a JSON API via `Plug.Cowboy` on port 4000. Start the server in your application before evaluating these cells.
+
+First check the catalog — all NBN specifications are initialised on startup:
+
+```elixir
+Req.get!("http://localhost:4000/catalog").body |> Jason.encode!(pretty: true) |> IO.puts()
+```
+
+Now retrieve all NBN Ethernet instances:
+
+```elixir
+Req.get!("http://localhost:4000/nbnEthernet").body |> Jason.encode!(pretty: true) |> IO.puts()
+```
+
+Or fetch the one we provisioned above by id:
+
+```elixir
+Req.get!("http://localhost:4000/nbnEthernet/#{pri.id}").body |> Jason.encode!(pretty: true) |> IO.puts()
+```
+
 ## What Next?
 
 You've provisioned a complete NBN Ethernet access — NTD, UNI, AVC, CVC, NNI Group, and NNI — and seen how the `mine` actions propagate technology, speeds, CVLAN and port assignments up the resource hierarchy automatically.

lib/diffo_example/application.ex

@@ -9,6 +9,11 @@ defmodule DiffoExample.Application do
 
   @impl true
   def start(_type, _args) do
-    Supervisor.start_link([], strategy: :one_for_one)
+    children = [
+      {Plug.Cowboy, scheme: :http, plug: DiffoExample.Nbn.Router, options: [port: 4000]},
+      {Task, &DiffoExample.Nbn.Initializer.init/0}
+    ]
+
+    Supervisor.start_link(children, strategy: :one_for_one, name: DiffoExample.Supervisor)
   end
 end

lib/nbn/api_router.ex

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: 2025 diffo_example contributors <https://github.com/diffo-dev/diffo_example/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule DiffoExample.Nbn.ApiRouter do
+  @moduledoc false
+  use AshJsonApi.Router,
+    domains: [DiffoExample.Nbn],
+    open_api: "/open_api"
+end

lib/nbn/catalog.ex

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2025 diffo_example contributors <https://github.com/diffo-dev/diffo_example/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule DiffoExample.Nbn.Catalog do
+  @moduledoc """
+  Diffo - TMF Service and Resource Management with a difference
+
+  Catalog - the NBN resource and service catalog.
+  """
+
+  def list do
+    Diffo.Provider.list_specifications!()
+    |> Enum.map(fn spec ->
+      Jason.OrderedObject.new(
+        id: spec.id,
+        href: spec.href,
+        name: spec.name,
+        version: spec.version,
+        description: spec.description,
+        category: spec.category
+      )
+    end)
+  end
+end

lib/nbn/initializer.ex

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2025 diffo_example contributors <https://github.com/diffo-dev/diffo_example/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule DiffoExample.Nbn.Initializer do
+  @moduledoc """
+  Diffo - TMF Service and Resource Management with a difference
+
+  Initializes the NBN domain's specifications in the catalog on application startup,
+  so the catalog is populated before any instances are built.
+  """
+
+  alias Diffo.Provider.Instance.Specification
+
+  def init do
+    DiffoExample.Nbn
+    |> Ash.Domain.Info.resources()
+    |> Enum.each(fn module ->
+      try do
+        Specification.upsert_specification(module)
+      rescue
+        _ -> :ok
+      end
+    end)
+  end
+end

lib/nbn/nbn.ex

@@ -13,7 +13,8 @@ defmodule DiffoExample.Nbn do
   CVC (aggregates AVCs, terminates at NNI Group), NNI Group, and NNI.
   """
   use Ash.Domain,
-    otp_app: :diffo
+    otp_app: :diffo,
+    extensions: [AshJsonApi.Domain]
 
   alias DiffoExample.Nbn.NbnEthernet
   alias DiffoExample.Nbn.Uni
@@ -27,6 +28,78 @@ defmodule DiffoExample.Nbn do
     description "An example showing how TMF Resources for a fictional NBN domain can be extended from the Provider domain"
   end
 
+  json_api do
+    routes do
+      base_route "/nbnEthernet", NbnEthernet do
+        index :read
+        get :read
+        post :build
+        patch :define
+        patch :relate, route: "/:id/relate"
+        patch :mine, route: "/:id/mine"
+        delete :destroy
+      end
+
+      base_route "/uni", Uni do
+        index :read
+        get :read
+        post :build
+        patch :define
+        patch :relate, route: "/:id/relate"
+        patch :mine, route: "/:id/mine"
+        delete :destroy
+      end
+
+      base_route "/avc", Avc do
+        index :read
+        get :read
+        post :build
+        patch :define
+        patch :relate, route: "/:id/relate"
+        patch :mine, route: "/:id/mine"
+        delete :destroy
+      end
+
+      base_route "/ntd", Ntd do
+        index :read
+        get :read
+        post :build
+        patch :define
+        patch :relate, route: "/:id/relate"
+        delete :destroy
+      end
+
+      base_route "/cvc", Cvc do
+        index :read
+        get :read
+        post :build
+        patch :define
+        patch :relate, route: "/:id/relate"
+        patch :mine, route: "/:id/mine"
+        delete :destroy
+      end
+
+      base_route "/nniGroup", NniGroup do
+        index :read
+        get :read
+        post :build
+        patch :define
+        patch :relate, route: "/:id/relate"
+        delete :destroy
+      end
+
+      base_route "/nni", Nni do
+        index :read
+        get :read
+        post :build
+        patch :define
+        patch :relate, route: "/:id/relate"
+        delete :destroy
+      end
+
+    end
+  end
+
   resources do
     resource NbnEthernet do
       define :get_nbn_ethernet_by_id, action: :read, get_by: :id
@@ -83,5 +156,6 @@ defmodule DiffoExample.Nbn do
       define :define_nni, action: :define
       define :relate_nni, action: :relate
     end
+
   end
 end

lib/nbn/resources/avc.ex

@@ -21,7 +21,12 @@ defmodule DiffoExample.Nbn.Avc do
 
   use Ash.Resource,
     fragments: [BaseInstance],
-    domain: Nbn
+    domain: Nbn,
+    extensions: [AshJsonApi.Resource]
+
+  json_api do
+    type "avc"
+  end
 
   resource do
     description "An Ash Resource representing an Access Virtual Circuit (AVC)"
@@ -110,9 +115,9 @@ defmodule DiffoExample.Nbn.Avc do
 
   # mines related resource to characteristics
   def mine_related(changeset, _context) when is_struct(changeset, Ash.Changeset) do
-    reverse_relationships = Ash.Changeset.get_attribute(changeset, :reverse_relationships)
+    avc = Ash.load!(changeset.data, [reverse_relationships: [:characteristics]])
 
-    cvlan = {:cvlan, Diffo.Unwrap.unwrap(hd(hd(reverse_relationships).characteristics).value)}
+    cvlan = {:cvlan, Diffo.Unwrap.unwrap(hd(hd(avc.reverse_relationships).characteristics).value)}
 
     Ash.Changeset.force_set_argument(changeset, :characteristic_value_updates, avc: [cvlan])
   end