Back to top

Livefyre App Service

This Web Service manages App objects that end-users will be creating. Apps are versioned resources composed of Component objects that represent chunks of functionality that can be installed to and run in a web page.

Components are configured before they are run. The Component developer can dictate default config values, and the component user can override these config values, as long as the provided values are in line with the component’s configSchema, which may also provide defaults.

Authorization

All requests require authorization, which is claimed via lftokens in the HTTP authorization header. Every request requires a valid lftoken.

Authorization: lftoken {theLfToken}

For browser compatibility, the lftoken may also be provided using the lftoken query param. If you are making these requests from a browser, it is strongly recommended that you only pass the lftoken in the querystring if the browser has no way of passing an ‘Authorization’ header with cross-origin requests (e.g. IE<=9).

GET /apps?lftoken={theLfToken}

Cross Origin Resource Sharing (CORS)

All APIs in this service have CORS Headers that should allow modern browsers to request them from any origin using XmlHttpRequest.

Some browsers, like IE8 and IE9, do not support full CORS capabilities. To support browsers like these, this service serves ./cors.html, which is intended to be used as an iframe proxy to circumvent the same origin policy. You should use an easyXDM Rpc object to communicate with it, and there is an exposed request method that will make AJAX requests.

Apps

Apps are composed from one or more elements, which currently must be powered by a configured Component. Apps can be created and configured by end-users using App Designer in Livefyre Studio.

Apps are named, versioned resources that can execute on a webpage. Many many versions may be created via the “Autosave” feature of App Designer.

Apps can be requested across several pages and customer environments. For example, an App creation team may wish to maintain the App’s lifecycle across versions for production, staging, development, and feature experiments. This team would want their test pages to have different versions deployed than their production pages. For these use cases, clients can create Tags which are named, movable pointers to specific versions of an app.

Apps have the following fields

  • id - UUID of the App. Never changes. Provisioned by this service.

  • version - The version of this App you are looking at.

  • title - Title of the App to show in a list of Apps All versions can be accessed by version at any point.

  • owner - Object describing the entity that owns the App. Currently there is only a ‘urn’ property.

  • createdAt - When this app was originally created

  • updatedAt - When this app was last updated

  • updatedBy - Object describing the entity that last updated the App. Currently there is only a ‘urn’ property.

  • groups - Array - Set of Group URNs that this App belongs to. These must be URNs of Livefyre Sites or Networks (e.g. urn:livefyre:a-network.fyre.co:site=siteId), and to create an App in a group, the requesting user must have moderator priveleges in that group.

  • elements - Array - The set of elements that make up this App

    Each element MUST have

    • component - An Object describing the software component that powers this element.
    • config - An Object describing configuration values provided by the app creator. This will be used to execute the Component. The format of config varies depending on the component being configured.

App List

Could be used by App Manager to show me a list of Apps I may want to edit, and let me create new apps.

Get Apps
GET/apps/

Get a list of apps.

Requires authorization, and the result set should only contain apps that the requesting user has authorization to see. A user is authorized to see an app if they are its owner or if they have moderator priveleges in any one of the App’s groups.

Example URI

GET /apps/
URI Parameters
HideShow
sort
string (optional) Example: -createdAt

What field to sort on. Leading - indicates descending sort.

Choices: createdAt -createdAt updatedAt -updatedAt

usingComponent
string (optional) Example: streamhub-wall

Only show apps that contain an element powered by the provided component name.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "apps": [
    {
      "owner": {
        "urn": "urn:urn:livefyre:studio-qa-0.fyre.co:user=system"
      },
      "createdAt": 1414532964544,
      "elements": [
        {
          "component": {
            "name": "component-for-service",
            "version": "0.0.0",
            "main": "http://livefyre-cdn-dev.s3.amazonaws.com/libs/streamhub-wall/v3.3.0-component.6/streamhub-wall.min.js",
            "configSchema": {}
          },
          "config": {
            "collection": {
              "network": "livefyre.com",
              "siteId": "313878",
              "articleId": "1",
              "environment": "livefyre.com"
            },
            "cardBackgroundColor": "#333"
          },
          "id": "0"
        }
      ],
      "id": "54173a972e91bf0000000001",
      "title": "My First App!",
      "updatedAt": 1414532964544,
      "updatedBy": {
        "urn": "urn:urn:livefyre:studio-qa-0.fyre.co:user=system"
      },
      "version": "0",
      "groups": []
    }
  ]
}

Create New App
POST/apps/

Create a new app.

Requires authorization to ‘createApp’ in all of the App’s groups. Currently users can create apps in a group if they have Livefyre Moderation privileges in that group.

Example URI

POST /apps/
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "title": "Example App w/ streamhub-wall",
  "groups": [
    "urn:livefyre:network.fyre.co:site=siteId"
  ],
  "elements": [
    {
      "component": {
        "name": "streamhub-wall",
        "version": "3.3.0-component.6"
      },
      "config": {
        "collection": {
          "network": "livefyre.com",
          "siteId": "313878",
          "articleId": "1",
          "environment": "livefyre.com"
        },
        "cardBackgroundColor": "pink"
      }
    }
  ]
}
Response  201
HideShow
Headers
Location: 
Body
{
  "id": "5408ddbb82f3910000000002",
  "url": "/apps/5408ddbb82f3910000000002"
}

App

The Latest version of an app by id, and any unversioned metadata.

Get an App
GET/apps/{id}

Get the latest version of an app by id, and any unversioned metadata.

Requires authorization to ‘getApp’. Users have ‘getApp’ permission if they are the app owner or a moderator in any one of the App’s groups.

Example URI

GET /apps/some-guid
URI Parameters
HideShow
id
string (required) Example: some-guid

The ID of the desired app.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "apps": [
    {
      "id": "some-guid",
      "version": "0.0.0",
      "title": null,
      "owner": null,
      "createdAt": null,
      "updatedAt": null,
      "updatedBy": null,
      "elements": null
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "App not found"
}

Update an App
PATCH/apps/{id}

Update an app to change its elements, title, or other fields.

Example URI

PATCH /apps/some-guid
URI Parameters
HideShow
id
string (required) Example: some-guid

The ID of the desired app.

Request
HideShow

Updates are represented as JSONPatch documents that are applied to the same JSON response you’d receive from a GET request to this URL.

Your JSONPatch document MUST enclode a “test” operation that tests the app version you’re updating. This is to prevent unintended lost data when concurrent clients are performing updates.

The only editable properties on element components are the component’s name and version, which must correspond to a Component in this service.

When changing elements’ Components or configs, the request will not succeed unless the new element config validates against that element’s Component’s configSchema.

Body
[
  {
    "op": "test",
    "path": "/apps/0/version",
    "value": "85"
  },
  {
    "op": "replace",
    "path": "/apps/0/elements/0/config",
    "value": {
      "configField": "configValue"
    }
  },
  {
    "op": "replace",
    "path": "/apps/0/elements/0/component/version",
    "value": "3.3.0"
  }
]

App Version List

A list of the latest versions of an app by ID.

Get App Version List
GET/apps/versions/

Get the latest versions of a single app by id.

Requires ‘getAppVersions’ permission on the app. A user can ‘getAppVersions’ if they are the owner of the app or a moderator of any one if its groups.

Example URI

GET /apps/versions/
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "apps": [
    {
      "id": "some-guid",
      "version": "0.0.0",
      "title": null,
      "owner": null,
      "createdAt": null,
      "updatedAt": null,
      "updatedBy": null,
      "elements": null
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": "App not found"
}

App Version

A single App at a specific Version

Get App Version
GET/apps/{id}/versions/{version}

Get a single app at a specific version

Requires ‘getAppVersions’ permission on the app. A user can ‘getAppVersions’ if they are the owner of the app or a moderator of any one if its groups.

Example URI

GET /apps/some-guid/versions/0
URI Parameters
HideShow
id
string (required) Example: some-guid

The App ID

version
string (required) Example: 0

The version of the app

Response  200
HideShow
Headers
content-type: application/json; charset=utf-8
Body
{
  "apps": [
    {
      "id": "some-guid",
      "version": "0",
      "title": null,
      "owner": null,
      "createdAt": null,
      "updatedAt": null,
      "updatedBy": null,
      "elements": null
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": "App Version not found"
}

Restore App Version

POST/apps/versions/restore

Update the app to be exactly like an older version of the same app. This will create a new, highest version number.

Requires ‘updateApp’ permission on the app. A user can ‘updateApp’ if they are the owner of the app or a moderator of any one if its groups.

Example URI

POST /apps/versions/restore
Response  201
HideShow
Headers
content-type: application/json; charset=utf-8
Body
{
  "apps": [
    {
      "id": "some-guid",
      "version": "0",
      "title": null,
      "owner": null,
      "createdAt": null,
      "updatedAt": null,
      "updatedBy": null,
      "elements": null
    }
  ]
}

App Tag List

A list of the tags for an app

Get Tags for App
GET/apps/{id}/tags/{?embedApps}

Get all tags for an app

Requires ‘getAppTags’ permission on the app. A user can ‘getAppTags’ if they are the owner of the app or a moderator of any one if its groups.

Example URI

GET /apps/some-guid/tags/?embedApps=true
URI Parameters
HideShow
id
string (required) Example: some-guid

The App ID

embedApps
boolean (optional) Default: false Example: true

Whether to also include an apps array on the response that includes the full app version object for each tag.

Response  200
HideShow
Headers
content-type: application/json; charset=utf-8
Body
{
  "tags": [
    {
      "appId": "some-guid",
      "name": "published",
      "appVersion": "0"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": "App with id and tag not found"
}

App Tags

A single Tag for an App

Get Tag for an App
GET/apps/{id}/tags/{tag}{?embedApps}

Get a single tag for an App

Requires ‘getAppTags’ permission on the app. A user can ‘getAppTags’ if they are the owner of the app or a moderator of any one if its groups.

Example URI

GET /apps/some-guid/tags/published?embedApps=true
URI Parameters
HideShow
id
string (required) Example: some-guid

The App ID

tag
string (required) Example: published

The tag of the app

embedApps
boolean (optional) Default: false Example: true

Whether to also include an apps array on the response that includes the full app version object for each tag.

Response  200
HideShow
Headers
content-type: application/json; charset=utf-8
Body
{
  "tags": [
    {
      "appId": "some-guid",
      "name": "published",
      "appVersion": "0"
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": "App with id and tag not found"
}

Tag an App Version
PUT/apps/{id}/tags/{tag}{?embedApps}

PUT a tag for an App Version

Requires ‘createAppTag’ permission on the app tag. A user can ‘createAppTag’ if they are the owner of the app or a moderator of any one if its groups.

Example URI

PUT /apps/some-guid/tags/published?embedApps=true
URI Parameters
HideShow
id
string (required) Example: some-guid

The App ID

tag
string (required) Example: published

The tag of the app

embedApps
boolean (optional) Default: false Example: true

Whether to also include an apps array on the response that includes the full app version object for each tag.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "appVersion": "an-app-version"
}
Response  201

Delete a Tag
DELETE/apps/{id}/tags/{tag}{?embedApps}

DELETE a tag for an App

Requires ‘deleteAppTag’ permission on the app tag. A user can ‘deleteAppTag’ if they are the owner of the app or a moderator of any one if its groups.

Example URI

DELETE /apps/some-guid/tags/published?embedApps=true
URI Parameters
HideShow
id
string (required) Example: some-guid

The App ID

tag
string (required) Example: published

The tag of the app

embedApps
boolean (optional) Default: false Example: true

Whether to also include an apps array on the response that includes the full app version object for each tag.

Request
HideShow
Headers
Content-Type: application/json
Response  204

Tagged Apps

A single App Version for a Tag

Get App at Tag
GET/apps/{id}/tagged/{tag}

Requires ‘getAppTag’ permission on the app. A user can ‘getAppTag’ if they are the owner of the app or a moderator of any one if its groups.

Get a single app at a specific tag

Example URI

GET /apps/some-guid/tagged/published
URI Parameters
HideShow
id
string (required) Example: some-guid

The App ID

tag
string (required) Example: published

The tag of the app

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "apps": [
    {
      "owner": {
        "urn": "urn:urn:livefyre:studio-qa-0.fyre.co:user=system"
      },
      "createdAt": 1414532964544,
      "elements": [
        {
          "component": {
            "name": "component-for-service",
            "version": "0.0.0",
            "main": "http://livefyre-cdn-dev.s3.amazonaws.com/libs/streamhub-wall/v3.3.0-component.6/streamhub-wall.min.js",
            "configSchema": {}
          },
          "config": {
            "collection": {
              "network": "livefyre.com",
              "siteId": "313878",
              "articleId": "1",
              "environment": "livefyre.com"
            },
            "cardBackgroundColor": "#333"
          },
          "id": "0"
        }
      ],
      "id": "54173a972e91bf0000000001",
      "title": "My First App!",
      "updatedAt": 1414532964544,
      "updatedBy": {
        "urn": "urn:urn:livefyre:studio-qa-0.fyre.co:user=system"
      },
      "version": "0",
      "groups": []
    }
  ]
}
Response  404
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "error": "App with id and tag not found"
}

Tags

Tags are used to identify App Versions.

Tag List

Get Tags for a set of Apps
GET/tags/{name}

A list of tags with the name, for a set of app ids.

Example URI

GET /tags/published
URI Parameters
HideShow
name
string (required) Example: published

The Name of the tag

appId
string (required) Example: an-app-id

The id of the app, repeat for many apps

Response  200
HideShow
Headers
content-type: application/json; charset=utf-8
Body
{
  "tags": [
    {
      "appId": "some-guid",
      "name": "published",
      "appVersion": "0"
    }
  ]
}

Components

Apps are composed from one or more elements, each of which is powered by a Components. Components are created by developers, and are meant to be instantiated many times with many configurations.

They may be visual components that can be configured to render in an HTMLElement. Or they could be headless components, and/or components that require no config at all.

Components have the following fields

Required

  • name - Component Name. Provided by the creator of the component. Like an ‘articleId’ of a Collection. Mutability TBD.

  • version - The version of this component you are looking at. Some fields are mutable and versioning is in our Problem Domain

  • id - Unique ID of the Component. Never changes. Defaults to a GUID.

  • description - A block of plain text describing the component to app creators

  • main - URL of the component script to run on webpages

  • configSchema - A JSONSchema Object describing the allowed and default config values for this component

Component List

A List of known components.

Get Components
GET/components/

Get a list of components.

App Designer may use this to show a list of available components that the user my add to their App.

Example URI

GET /components/
Response  200
HideShow
Headers
content-type: application/json; charset=utf-8
date: Wed, 09 Apr 2014 06:39:16 GMT
connection: keep-alive
Body
{
  "components": [
    {
      "id": "streamhub-map-GUID",
      "name": "streamhub-map",
      "version": "1.0.0",
      "main": "http://cdn.livefyre.com/libs/apps/Livefyre/streamhub-map/v1.0.0/streamhub-map.min.js"
    }
  ]
}

Create New Component
POST/components/

Create a new component

This is a privileged API. For the foreseeable future, only Livefyre Engineering will use it. Eventually, others may contribute their custom components. Or a Customer may wish to fork a Component, change the default configuration, and use it as a template.

Requires ‘createComponent’ permission. If you’d like authorization to create components, please contact ben@livefyre.com.

Example URI

POST /components/
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "streamhub-wall",
  "version": "2.3.0",
  "main": "http://cdn.livefyre.com/libs/apps/Livefyre/streamhub-wall/v2.3.0-build.188/streamhub-wall.min.js",
  "configSchema": {}
}
Response  201
HideShow
Headers
Location: /components/streamhub-wall
Body
{
  "url": "/components/streamhub-wall"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": "The componentId 'streamhub-me' already exists"
}

Component

A single Component, retrieved by name. The latest version will be returned.

Get Component
GET/components/{name}

Get a single component.

Example URI

GET /components/streamhub-wall
URI Parameters
HideShow
name
string (required) Example: streamhub-wall

The Name of the component

Response  200
HideShow
Headers
content-type: application/json; charset=utf-8
Body
{
  "name": "streamhub-wall",
  "version": "2.3.0",
  "latestVersion": null,
  "description": null,
  "main": "http://cdn.livefyre.com/libs/apps/Livefyre/streamhub-wall/v2.3.0-build.188/streamhub-wall.min.js"
}
Response  404
HideShow
Headers
content-type: application/json; charset=utf-8
Body
{
  "error": "404: No component found with name streamhub-wall"
}

Delete a Component
DELETE/components/{name}

Delete a single component

Requires ‘deleteComponent’ permission. If you’d like authorization to delete components, please contact ben@livefyre.com.

Example URI

DELETE /components/streamhub-wall
URI Parameters
HideShow
name
string (required) Example: streamhub-wall

The Name of the component

Response  204
Response  404
HideShow
Headers
content-type: application/json; charset=utf-8
Body
{
  "error": "Component not found"
}

Generated by aglio on 04 Dec 2021