Platform APIs

Fission Platform APIs

The ODD SDK platform API provides methods to work with Fission apps.

The platform API makes it possible to manage user apps and, combined with the ODD SDK filesystem methods, create and manage apps entirely from the browser.

Yes, you can build an app, that creates apps on behalf of the user! This is a way for developers to make use of the Fission Platform to build their own MicroSaaS business, including custom domains and other features for their users.

The API methods are prefixed with apps.

• apps.index: A list of all of your apps and their associated domain names

• apps.create: Creates a new app, assigns an initial subdomain, and sets an asset placeholder

• apps.publish: Publish a new app version

• apps.deleteByDomain: Destroy an app identified by domain

Permissions

Apps that use the platform API must request permission to work with a user's apps. Permissions are requested when a user signs in through the Fission Auth Lobby. See the requesting capabilities guide for more on requesting permissions.

Platform API permissions are requested at permissions.platform.apps in the configuration object.

import * as wn from '@oddjs/odd'

const permissions = {
  platform: {
    apps: "*",
  },
  // ... other permissions
}

// Create ODD SDK program with expected permissions
odd.program({ permissions }).then(program => {
  if (!program.session) {
    // We don't have the permissions yet. 
    // Let's send the user to auth.fission.codes and ask for them:
    program.capabilities.request()
  } else {
    // we're all set up! 🎉
  }
})

The value at permissions.platform.apps can be

• "*": Grant complete app management access for all of the user's apps

• An array of domain names, e.g. [ "an-app.fission.app", "another-app.fission.app" ]: Grant permission to manage specific apps. Those apps can be published or deleted.

Endpoints & Dependencies

These app function are a bit more low level than your usual ODD SDK functions. This is because these functions are specifically for the Fission architecture, while the rest of ODD SDK is not. We'll need two things to get started, the endpoints and the dependencies:

const endpoints = odd.fission.PRODUCTION // default, can also be fission.STAGING, depending on your used components
const dependencies = { crypto: program.components.crypto, reference: program.components.reference }

API

apps.index

Lists all user apps and their associated domain names.

Required permissions: { platform: { apps: "*" } } full app management permissions

Params: No parameters

Returns: App[] with the domain names, creation and modification times for each app

Example:

const index = await odd.apps.index(endpoints, dependencies)
// [ 
//   { domains: ['your-fission-deployment.fission.app'],
//     insertedAt: '<creation-time>',
//     modifiedAt: '<last-modified-time>',
//   } 
// ]

apps.create

Creates a new app, assigns an initial subdomain, and publishes a placeholder site.

Required permissions: { platform: { apps: "*" } } full app management permissions

Params:

• subdomain: string | null optional, set to null to generate a name

Returns: { domain: string } the subdomain of the newly created app

Example:

const newApp = await odd.apps.create(endpoints, dependencies, null)
// { domain: 'your-fission-deployment.fission.app' }

apps.publish

Publishes a new app version by IPFS CID. If the app does not exist yet, create the app first with apps.create.

Required permissions: Needs either permission for the app domain or full app management permissions. See Permissions.

Params:

• domain: string required

• cid: CID required

Returns: Nothing returned

Example:

import { decodeCID } from '@oddjs/odd/common/cid'

const cid = decodeCID('QmRVvvMeMEPi1zerpXYH9df3ATdzuB63R1wf3Mz5NS5HQN')

await odd.apps.publish(
  endpoints,
  dependencies,
  'your-fission-deployment.fission.app',
  cid
)

Retrieving the CID depends on where you have staged the app code. One convenient way to do this is to publish the app's HTML, CSS, JavaScript, and assets to a public directory in WNFS and retrieve the CID of that directory.

import * as Fission from "@oddjs/odd/common/fission"
import * as IPFS from "@oddjs/odd/components/depot/implementation/ipfs/index"
import { namespace } from "@oddjs/odd"

// Get an IPFS instance
const storage = odd.defaultStorageComponent(CONFIG)
const { ipfs } = await IPFS.nodeWithPkg(
  { storage },
  await IPFS.pkgFromCDN(IPFS.DEFAULT_CDN_URL),
  `${Fission.PRODUCTION.server}/ipfs/peers`,
  `${namespace(CONFIG)}/ipfs`,
  false
)

// The POSIX path where you published your app code in the public filesystem:
const appPath = odd.path.directory(
  'Apps',
  'your-fission-deployment'
  'Published'
)

// Get UnixFS CID for public directory
const rootCid = await fs.root.put()
const stats = await ipfs.files.stat(`/ipfs/${rootCid}/p/${odd.path.toPosix(appPath)}`)

// The CID you use to publish with the platform API:
const cid = stats.cid.toString()

// 🚀
await odd.apps.publish(endpoints, dependencies, 'your-fission-deployment.fission.app', cid)

apps.deleteByDomain

Delete an app by domain.

Required permissions: Needs either permission for the app domain or full app management permissions. See Permissions.

Params:

• url: string required

Returns: Nothing returned

Example:

await odd.apps.deleteByDomain(endpoints, dependencies, 'your-fission-deployment.fission.app')