Lesson 08

Embedded API boundaries

Keep host-provided APIs small and explicit when Lua scripts extend an application.

embedded
api
host

Good Code

src/review_script_api.lua

local api = {}

function api.add_note(review, text)
  -- The host API validates script input before mutating review state.
  assert(type(text) == "string", "note text must be a string")
  review.notes[#review.notes + 1] = text
end

return api

Bad Code

review_script_api.lua

local api = {}

function api.expose_review(review)
  -- Scripts receive the full mutable host object.
  return review
end

return api

Review Notes

What to review

Good Code

The good version exposes a narrow command and validates script input before changing host state.

Bad Code

The bad version hands the whole host object to scripts. A script can mutate fields the host does not expect, making failures hard to trace.

Takeaways

An embedded Lua API should expose narrow commands rather than raw host objects with broad mutation power.