Extension API

Everything needed to describe, package, publish and download an extension. Reads are public; writes need a credential.

The registry serves the catalog the IDE installs from. An extension is identity; each of its versions is a release, and a release owns the files it is made of. Nothing is publicly visible until both the extension and the version are approved.

Accounts, tokens and the Administrator role are covered separately in the User API. The examples below use:

New clients should use the /api/ prefix, for example GET /api/extensions. Existing paths such as /extensions remain supported and return the same JSON, regardless of the Accept header. The website catalog is separate at /add-extensions. All examples below use the preferred API base URL.

B=https://tucan.amlang.net/api
TOKEN=…            # your access token, from POST /users/login

The model

Four tables, each owning one thing:

The separations that matter:

• Identity vs release. The extension is created once and holds nothing that changes between releases. Everything releasable lives on the version, so an old version stays fully installable — its metadata is never overwritten by a newer one.
• Resource vs file. A resource says what a version needs and where it comes from. Only the ones we host have bytes: aminet and url resources have no extension_file row at all, and /r/{name} 404s for them. The registry serves only its own files.
• Approval on both. A new version can be staged while the published one keeps serving.

Extensions and applications

Every entry has a type, and it decides only which collection lists it.

Both use the same table, the same versions, the same resources and the same download URLs one level down; /applications/… mirrors /extensions/… exactly, filters included. The collections are disjoint: asking for an application under /extensions is a 404, not a redirect, and ids are unique across both, so nothing is reachable under the wrong one.

curl "$B/applications"                    # active applications, latest of each
curl "$B/applications/amstudio/v"         # its versions
curl -O "$B/applications/amstudio/v/2.1.0/amigaos/r/amstudio.lha"

Applications are published by whoever runs the registry, not by its users — an app update is not something a third party ships. Everything below is about extensions; applications only appear here because the IDE reads them through the same five endpoints.

Every endpoint

Reads are public and need nothing.

Who may write

There is no separate path for writing. An extension lives at one address, and the caller decides what is allowed there:

Tokens, sign-up and what each failure code means are in the User API.

extension.json — identity

{
  "localName":   "bebbossh",
  "name":        "BebboSSH",
  "description": "Bebbo's SSH2 suite for AmigaOS."
}

localName is the id: permanent, and in every URL. That is the whole shape — no version, no files, no platforms. Re-posting updates the name and description. No type here either; it comes from the collection you post to, so a manifest still carrying the old catalog's type works unchanged.

version.json — the release

{
  "version":      "1.0.0",
  "releaseNotes": "First release. Connection manager, key generation.",

  "path": ["vendor/bebbossh"],
  "permissions": ["system.execute", "internet"],

  "resources": [
    { "source": "registry", "platform": "amigaos",
      "name": "bebbossh-ext.lha", "format": "lha" },

    { "source": "aminet", "platform": "amigaos",
      "name": "bebbossh.lha", "folder": "vendor",
      "remoteIdentifier": "comm/net/bebbossh", "version": "2.4" }
  ],

  "menuItems": [
    { "name": "Add connection...", "script": "addConnection.js" },
    { "name": "Generate SSH key...", "command": "bebbosshkeygen -C \"${comment}\"",
      "form": "keygen.form.xml", "interactive": true }
  ],

  "fileEditors": [
    { "extension": ".dss", "viewTemplate": "pixler.view.xml",
      "onOpen": "openDss.js", "onSave": "saveDss.js" }
  ]
}

Resources

A resource is one file: an archive, or a bare executable. The registry stores files, never directory trees — which is why a resource name may not contain a slash. Inside the archive, structure it as you please.

Split along ownership rather than size. Ship your own files as a registry resource; reference third-party archives as aminet or url instead of mirroring them. Per-platform builds are separate resources with distinct platform values — give them distinct names too, so the download URLs stay self-describing.

How the folder comes together

An extension installs into one folder of its own, extensions/<id>/, and every resource declares the folder inside it where the resource is unpacked. Several archives can contribute to the same tree:

extensions/bebbossh/
  addConnection.js          <- your archive, folder blank -> the root
  connections.json
  vendor/                   <- the Aminet archive, folder "vendor"
    bebbossh/               <- the directory that archive carries internally
      bebbossh
      libcryptossh.library

Whatever structure an archive contains nests below its folder: an archive carrying its own bebbossh/ directory, given folder: "vendor", lands in vendor/bebbossh/ — not in vendor/.

folder cannot point outside the extension: no leading /, no .., and no : — on AmigaOS amStudio:extensions/other is absolute, so a colon is an escape rather than a separator.

Manifest references are resolved relative to the extension folder, and a resource's folder counts: unpack your scripts under folder: "scripts" and the manifest has to say scripts/addConnection.js. The useful check before uploading is not "is it flat" but "does it match what I reference":

lha l dist/bebbossh-ext.lha
unzip -l dist/bebbossh-ext.zip

Packing the parent directory by mistake is the common slip — everything gains a prefix and the manifest's references stop resolving. Pack from inside the folder when you want its contents at the root:

cd src && lha a ../dist/bebbossh-ext.lha *

path: making binaries reachable

Folders inside the extension folder to add to the IDE's path.

"path": ["vendor/bebbossh"]                       -> extensions/bebbossh/vendor/bebbossh
"path": ["vendor/bebbossh", "vendor/bebbossh/bin"]
"path": []                                        -> nothing added (scripts-only extensions)

path is where the binaries ended up: a resource's folder plus whatever directory the archive carries inside it. Change the one and the other has to follow. A scripts-only extension needs no entry at all — scripts are named by the manifest, not executed off the path. The same three things are rejected here as in folder, for the same reason: a leading /, any .., and any :.

Publishing

Three calls, and order matters: the extension must exist before a version, and a version must declare a resource before its bytes can be uploaded. Everything here carries your access token.

# 1. identity, once. You own what you create.
curl -X POST "$B/extensions" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' --data-binary @extension.json

# 2. the release, and every resource it is made of
curl -X POST "$B/extensions/bebbossh/v" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' --data-binary @version.json

# 3. the bytes - one call per registry resource, named exactly as declared
curl -X PUT "$B/extensions/bebbossh/v/1.0.0/amigaos/r/bebbossh-ext.lha" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/octet-stream' \
  --data-binary @dist/bebbossh-ext.lha

One upload per registry resource, addressed by platform and name — four registry resources means four PUTs, and a PUT for an undeclared name is a 400, not a silent create. aminet and url resources are only ever declared, never uploaded.

Releasing a new version of something that already exists

The extension is already there, so skip step 1 — it is version, then resources:

curl -X POST "$B/extensions/am-git/v" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' --data-binary @version.json

# one PUT per registry resource - three platforms means three calls
for p in amigaos morphos-ppc macos-arm; do
  curl -X PUT "$B/extensions/am-git/v/1.0.3/$p/r/am-git-$p.lha" \
    -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/octet-stream' \
    --data-binary @dist/am-git-$p.lha
done

# what actually landed? a resource with size: null was declared but never uploaded
curl -s "$B/extensions/am-git/v/1.0.3" -H "Authorization: Bearer $TOKEN" \
  | jq '.resources[] | {platform, name, size}'

Each platform needs its own entry in the version's resources[] with a matching name. Re-posting a version you have already published is how you correct it: resources are replaced wholesale, but one that survives keeps its uploaded bytes, and releaseDate does not move.

What gets rejected

Reading it back

curl "$B/extensions"                      # active extensions, latest version of each
curl "$B/extensions/bebbossh"             # identity + latest release info
curl "$B/extensions/bebbossh/v?page=1"    # versions, 10 per page, newest first
curl "$B/extensions/bebbossh/v/1.0.0"     # release info + resources overview
curl -O "$B/extensions/bebbossh/v/1.0.0/amigaos/r/bebbossh-ext.lha"

/r/{name} serves only the files we host. An aminet or url resource is described in the version's resource list — with its remoteIdentifier or url — and 404s here; the client fetches those from where they actually live.

Filtering and search

curl "$B/extensions?platform=amigaos"        # only what runs on amigaos
curl "$B/extensions?q=ssh"                   # search name and description
curl "$B/extensions?q=git&platform=amigaos"  # both

The listing is approved-only: an entry appears when the extension is approved and it has an approved version. Staged work never shows up, whoever is asking. ?all=1 includes unapproved entries and takes the newest version whatever its state, adding approved and versionApproved to each row — it needs the admin token, since a public all would defeat the point of approval, and returns 403 without one.

platform is matched against the latest version's resources — the same version the listing describes — so it cannot claim support the current release does not have. q is case-insensitive, and multiple words are AND: every term has to match something, so ?q=ssh+client narrows rather than widens. Results come back ranked, best first; without q they stay in name order.

The name always outranks the id, and the id always outranks the description, so searching git puts the extension called git above one that merely mentions it in its blurb. The id is searched at all because the display name often is not what you would type — ?q=amlang-toolchain finds "AmLang Toolchain", which contains no such string. There is no search on the version endpoints; the listing is the search surface.

If a version is withdrawn

Approval says published; active says still in circulation. A release found to be malicious, or broken badly enough that nobody should install it, is withdrawn by the registry's operators rather than un-approved — un-approving would describe it as pending review, which it is not.

It takes effect immediately and everywhere: the version stops being the latestVersion and the next newest published one takes over, it disappears from /extensions/{id}/v, /extensions/{id}/v/{version} becomes a 404, and its downloads 404 too — including for anyone already holding the URL. Nothing is deleted, so it can be put back.

Releasing over it is the usual answer: bump the version, post a new version.json, upload its bytes. The previous version keeps its own metadata and files and stays installable at its own URL, which is the point of versioned metadata.