guide documentation

[[api]]

API

By Goblin Docs ~ 8 min read

In Goblin, an API is not some abstract buzzword.

It means something very simple:

you put a Goblin script inside the api/ folder
Goblin Host maps a request path to that script
the script runs
its output becomes the HTTP response

That is the whole idea.

The Basic Rule

Tip

Goblin maps request paths directly to API scripts.

Like so:

/api/<name>  →  api/<name>.gbln

If the script exists, Goblin executes it. :::

For example, a request for:

/api/passwords

will cause Goblin Host to look for:

api/passwords.gbln

If that file exists, Goblin executes it.

Example

Suppose your project contains:

api/
  passwords.gbln

If the server is running and you visit:

http://localhost:5173/api/passwords

Goblin Host executes:

api/passwords.gbln

Whatever that script outputs becomes the HTTP response.

Static Files vs API Scripts

This is the most important distinction to understand.

Warning

Goblin only executes scripts inside the api/ folder.

If a .gbln file exists anywhere else in your site, Goblin Host will treat it as a static file and serve or download it instead of executing it.

For example:

docs/passwords.gbln

If you visit that path in the browser, Goblin will not execute it.

It will simply send the file.

So the rule is:

api/*.gbln → executable server scripts
everything else → static site content

API Location in Multi-Site Projects

When Goblin Host is serving multiple sites (for example using subdomains),
each site can have its own api/ folder.

Tip

API scripts are resolved relative to the current site root.

For example, suppose your docroot looks like this:

dist/
  goblin/
    api/
      password.gbln
  sheriff/
    api/
      test.gbln
  vekke/
    api/
      generator.gbln

If Goblin Host is running and your local domains resolve like this:

goblin.localhost
sheriff.localhost
vekke.localhost

Then the APIs resolve independently:

http://goblin.localhost:4242/api/password
    → dist/goblin/api/password.gbln

http://sheriff.localhost:4242/api/test
    → dist/sheriff/api/test.gbln

http://vekke.localhost:4242/api/generator
    → dist/vekke/api/generator.gbln

Each site executes only the scripts inside its own api/ directory.

This makes it easy to develop and test multiple Goblin projects at the same time.

Why the api Folder Exists

The api/ folder creates a clear boundary.

It tells Goblin Host:

these files are meant to run
everything else is just site content

This prevents random .gbln files from being executed simply because they exist somewhere in the project.

What APIs Are Used For

Goblin APIs are commonly used for:

generators
form handlers
JSON endpoints
server-side utilities
development tools
lightweight backend logic

A project like Chaos Cauldron can place generator scripts inside api/ and call them through the browser.

Plain-English Mental Model

Note

A static file is something Goblin Host sends.

An API script is something Goblin Host runs.

So:

/docs/index.html

gets sent.

But:

/api/passwords

gets mapped to a Goblin script and executed.

In Practice

A simple Goblin project might look like this:

my-site/
  index.html
  docs/
    guide.html
  api/
    passwords.gbln
    users.gbln

Then:

/ serves index.html
/docs/guide.html serves a static document
/api/passwords executes api/passwords.gbln
/api/users executes api/users.gbln

Relation to Goblin Host

The api/ system is part of Goblin Host.

Goblin Host is the server. The api/ folder is where the server looks for executable request handlers.

If Goblin Host is not running, the API scripts do nothing.

Why This Is Nice

Goblin does not require a large web framework just to create a callable endpoint.

You simply place a script inside api/, run Goblin Host, and call the route.

This makes it very easy to build lightweight tools and dynamic features without a lot of ceremony.