Three easy-to-mix topics links · empty results · API limits

A. Absolute URLs - why matters

The platform injects on every app page. Relative URLs resolve from the app root, not from a template folder like blog/detail.html.

site_url in JS is always the platform domain - it can differ in host from when the app uses a custom domain. Prefer the origin from the tag.

Rule: Navigation links - getAbsoluteUrl(slug) or href="slug" (no leading /, no .., no .html). The slug must exist in routes.json (addRoute).

Helper - paste into app HTML

/** Prefer  - works with custom domains too */
function getAppBaseUrl() {
  const base = document.querySelector('base[href]')?.href
  if (base) return base.replace(/\/$/, '') + '/'
  const site = (window.appifio?.global?.apps?.site_url || window.location.origin).replace(/\/$/, '')
  const name = window.appifio?.global?.apps?.url_name || ''
  return name ? `${site}/${name}/` : `${site}/`
}

/** path = route slug: '' | 'admin' | 'my-post' | 'tag/javascript' */
function getAbsoluteUrl(path) {
  const base = getAppBaseUrl().replace(/\/$/, '')
  const segment = String(path || '').replace(/^\//, '')
  return segment ? `${base}/${segment}` : `${base}/`
}

B. Empty data & required routes

Two separate ideas - do not mix them:

B.1 - First data-store reads

async function loadBlogs() {
  const result = await appifio_client.appifio_readList('blog.json', ['id','title','slug'])
  if (result?.success) return result.data.content || []  // [] first time - normal
  return []
}

// First post - backend creates the ledger
await appifio_client.appifio_appendData('blog.json', { title, slug, content })

// Flat config - keep defaults if empty
let config = { theme: 'light' }
const res = await appifio_client.appifio_readFile('config.json')
if (res?.success && res.data.content && typeof res.data.content === 'object') {
  config = res.data.content
}

// Expect failure when the file is missing - data store does NOT do that
if (!result.success) { /* never on first read */ }

// JSON.parse - Aura already parsed
const items = JSON.parse(result.data.content)

// writeFile for a list - breaks indexed sharding
await appifio_client.appifio_writeFile('blog.json', JSON.stringify([...]))

B.2 - Routes required for visitor URLs

By default only /urlname/ serves index.html. Every other slug must have an entry in routes.json - otherwise visitors get a 404 (unrelated to the data-store API).

// ❌ WRONG - data exists but visitor gets 404
await appifio_client.appifio_appendData('blog.json', blogData)

// ✅ RIGHT - data + route + HTML template already on FS
const { data: { id } } = await appifio_client.appifio_appendData('blog.json', blogData)
await appifio_client.appifio_addRoute(blogData.slug, 'blog/detail.html', 'blog')

// Nested tag / category routes
await appifio_client.appifio_addRoute('tag/javascript', 'blog/tag.html', 'tag')
await appifio_client.appifio_addRoute('category/tech', 'blog/category.html', 'category')

// Delete post → remove matching route
await appifio_client.appifio_updateData('blog.json', id, null)
await appifio_client.appifio_removeRoute(slug)

addRoute maps slug → HTML file on the physical FS - blog/detail.html must exist (Panel or writeFsFile). Method detail: AM05.

C. Rate limit & IP block

Limits are counted per IP + link (url_name) - each app is independent.

When an IP is blocked: HTTP 429, client maps err.blocked === true. You do not get remaining time or a detailed reason - UI should say a generic “Try again later”.

try {
  await appifio_client.appifio_appendData('contacts.json', data)
} catch (err) {
  if (err.blocked) {
    alert('IP temporarily blocked due to too many API calls. Please try again later.')
    return
  }
  if (err.httpStatus === 401) { /* session expired - go to login */ }
  throw err
}

Appifio Creator · Method series · AM10