Skip to main content

Which filesystem route should I use?

This page is the fast answer to a common integration problem: several AetherFS routes can look similar until you understand the workflow boundary each one is for.

If you need to stop two users or tools from editing the same path at once​

Use the collaboration file lock routes:

  • /v1/sessions/{sessionId}/files/lock
  • /v1/sessions/{sessionId}/files/renew-lock
  • /v1/sessions/{sessionId}/files/unlock
  • /v1/sessions/{sessionId}/files/list-locks

Choose these when:

  • the workflow is user-facing
  • a lock should have a lease/TTL
  • you want an explicit lock token
  • the client is a product or collaboration tool

If you need POSIX-compatible locking semantics​

Use the POSIX lock routes:

  • :getPosixLock
  • :setPosixLock
  • :setPosixLockBlocking
  • :flock
  • :funlock

Choose these when:

  • you need kernel-style lock behavior
  • your client is translating filesystem semantics
  • range locks matter
  • the lock owner is represented as a POSIX-style owner structure

Do not use these as your first choice for ordinary review or editor coordination unless you really need POSIX fidelity.

If you need path-local metadata that behaves like filesystem metadata​

Use xattrs:

  • :setXattr
  • :getXattr
  • :listXattrs
  • :removeXattr

Choose xattrs when:

  • the metadata belongs to a specific path
  • it should travel with that path
  • it is better modeled as filesystem metadata than as a workflow note

Good examples:

  • tool hints
  • classification markers
  • lightweight path-specific metadata

If you need human-facing review notes or workflow commentary​

Do not use xattrs.

Use:

  • annotations for durable review comments
  • cache entries for structured workflow state
  • bus messages for event-style progress

This distinction matters:

  • xattrs are metadata on a file
  • annotations are review data
  • cache is keyed workflow data
  • bus is event communication

If you need to know which bytes already exist in CAS​

Use:

  • :getCasExtents

Choose this when:

  • you want to plan sparse or borrowed writes
  • you want to reuse existing CAS-backed ranges
  • your client cares about byte-level reuse, not just path-level metadata

Do not use it for ordinary file browsing. The manifest is the right starting point for that.

If you need partial or sparse writes​

Use:

  • /patchSegments

Choose this when:

  • you are updating part of a file
  • you want conflict handling at the segment level
  • you want to combine inline bytes, holes, or borrowed CAS chunks

If you just need whole-file create/replace/delete, use the simpler write/delete or batch routes instead.

If you need a tree view or file browser​

Use:

  • /manifest

Do not start with CAS extents, xattrs, or lock routes. Those are specialized control surfaces, not discovery surfaces.

Rule of thumb​

Use:

  • file locks for collaboration
  • POSIX locks for filesystem compatibility
  • xattrs for path metadata
  • annotations for review notes
  • cache for structured session state
  • CAS extents for byte reuse planning
  • patchSegments for partial/sparse mutation
  • manifest for discovery

See also: