Uploading Assets Workflow

The process for uploading a file to the Live Editor system for use in the theme and/or content.

Live Editor stores its assets on Amazon’s Simple Storage Service (S3). This allows for a familiar process for uploading files into the cloud and relatively easy integration with many client- and server-side libraries.

There are a few steps involved with this workflow:

  1. Retrieve an S3 signature from the Live Editor API.
  2. Use the signature to upload the file directly to a temporary S3 bucket.
  3. Notify the Live Editor API of the completed file upload.
  4. [optional] If the asset is for use within the site’s theme, associate it with a theme asset record.
  5. Poll the Live Editor API for status on its processing of the uploaded file.

1. Retrieve an S3 signature from the Live Editor API

The first step is to ask the Live Editor API for a signature that your client can then pass on to Amazon S3.

To do that, communicate with the Upload Signatures API endpoint:

Request 

      POST https://coffee.api.liveeditorapp.com/upload-signatures HTTP/1.1
      Accept: application/vnd.api+json

Response 

      HTTP/1.1 200 OK
      Content-Type: application/vnd.api+json
      
      {
        "data": {
          "type": "upload-signatures",
          "id": "3a32f563-c336-4c9b-9602-5962989620cf&qupt;,
          "links:" {
            "self": "https://coffee.api.liveeditorapp.com/upload-signatures/3a32f563-c336-4c9b-9602-5962989620cf"
          }
          "attributes" {
            "filename": "images/water.jpg",
            "key": "1234/1234567890/images/water.jpg",
            "acl": "private",
            "content-type": "image/jpeg",
            "policy": "eyJleHBpcmF0aW8uIjoiMjAxNi0wMy0u...",
            "endpoint": "https://s3.amazonaws.com/uploads.liveeditor",
            "x-amz-credential": "VKIAI67ZPNBGNIXAFQTQ/20160302/us-east-1/s3/aws4_request",
            "x-amz-algorithm": "AWS4-HMAC-SHA256",
            "x-amz-date": "20120423T182543Z",
            "x-amz-signature": "b88837ce4394b0f5b25532074c1a232bd83b76de081f1e445a305d9f2745a0f7"
          }
        }
      }

See the Upload Signature API Model documentation for more information about the various attributes returned by Live Editor.

2. Use the signature to upload the file directly to a temporary S3 bucket

With the signature data on hand, your client can then PUT the file to Live Editor’s temporary S3 bucket.

You can review the technical docs for uploading a file to S3 using this information, but you’ll likely want to use a library compatible with your programming language of choice to get the job done.

3. Notify the Live Editor API of the completed file upload

Once the file has been uploaded to S3 successfully, your client needs to notify Live Editor with some of the data returned by S3. This is done through the Asset Uploads endpoint.

The call will look something like this:

Request 

      POST https://coffee.api.liveeditorapp.com/asset-uploads HTTP/1.1
      Accept: application/vnd.api+json
      
      {
        "data": {
          "type": "asset-uploads",
          "attributes": {
            "file-name": "logo.png",
            "key": "c97d0973-8a5c-4300-a70c-58e837c8c90c/1483810832535/logo.png",
            "content-type": "image/png",
            "file-size": 22366,
            "user-agent": "My Live Editor API Client v1"
          }
        }
      }

Response 

      HTTP/1.1 202 Accepted
      Content-Type: application/vnd.api+json
      
      {
        "data": {
          "id": "1737042d-3151-4fa4-bdb8-5a87a8f2d6fd",
          "type": "asset-uploads",
          "links": {
            "self": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd"
          }
          "attributes": {
            "file-name": "logo.png",
            "key": "c97d0973-8a5c-4300-a70c-58e837c8c90c/1483810832535/logo.png",
            "content-type": "image/png",
            "file-size": 22366,
            "user-agent": "My Live Editor API Client v1",
            "status": "processing",
            "error-message": null,
            "created-at": "2012-04-23T18:25:43.511Z",
            "updated-at": "2012-04-23T18:25:43.511Z"
          },
          "relationships": {
            "asset": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/relationships/asset"
                "related": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/asset"
              },
              "data": null
            },
            "asset-file": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/relationships/asset-file"
                "related": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/asset-file"
              },
              "data": null
            }
          }
        }
      }

4. [optional] If the asset is for use within the site’s theme, associate it with a theme asset record

If this asset is being uploaded along with a theme, it needs to be associated with the theme via a Theme Asset record.

You can use the Theme Assets endpoint to associate the asset with the theme, along with its path within the assets folder of the theme’s directory structure:

Request 

      POST https://coffee.api.liveeditorapp.com/theme-assets HTTP/1.1
      Accept: application/vnd.api+json
      
      {
        "data": {
          "type": "theme-assets",
          "attributes": {
            "path": "images/logo.png"
          },
          "relationships": {
            "theme": {
              "data": {
                "type": "themes",
                "id": "f58fd537-1899-4c4b-b054-1e47cdb398ce"
              }
            },
            "asset": {
              "data": {
                "type": "assets",
                "id": "b170e7fe-fe7a-4a33-80cf-c328d49de967"
              }
            }
          }
        }
      }

Response 

      HTTP/1.1 201 Created
      Content-Type: application/vnd.api+json
      
      {
        "data": {
          "type": "theme-assets",
          "id": "21dc2397-f8af-483f-bbcf-9859f60a9e15",
          "links": {
            "self": "https://coffee.api.liveeditorapp.com/theme-assets/21dc2397-f8af-483f-bbcf-9859f60a9e15"
          },
          "attributes": {
            "path": "images/logo.png",
            "created-at": "2012-04-23T18:25:43.511Z",
            "updated-at": "2012-04-23T18:25:43.511Z"
          },
          "relationships": {
            "theme": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/theme-assets/21dc2397-f8af-483f-bbcf-9859f60a9e15/relationships/theme"
                "related": "https://coffee.api.liveeditorapp.com/theme-assets/21dc2397-f8af-483f-bbcf-9859f60a9e15/theme"
              },
              "data": {
                "type": "themes",
                "id": "f58fd537-1899-4c4b-b054-1e47cdb398ce"
              }
            },
            "asset": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/theme-assets/21dc2397-f8af-483f-bbcf-9859f60a9e15/relationships/asset"
                "related": "https://coffee.api.liveeditorapp.com/theme-assets/21dc2397-f8af-483f-bbcf-9859f60a9e15/asset"
              },
              "data": {
                "type": "assets",
                "id": "b170e7fe-fe7a-4a33-80cf-c328d49de967"
              }
            }
          }
        }
      }

5. Poll the Live Editor API for status on its processing of the uploaded file

Once the Asset Uploads endpoint has been notified of the upload, Live Editor will begin processing the uploaded file asynchronously. (Notice in the example above that the status attribute’s value is processing.)

While Live Editor is processing the file, your client can poll it periodically for updates on the status of the processing. Your client can use GET requests against the same Asset Uploads endpoint to stay updated on the status of the status attribute.

Once Live Editor is finished processing the file, the status will change to finished or error.

Example finished asset upload

A finished asset upload will link to the asset and asset-file that was finally published (as denoted in the relationships object):

Request 

      GET https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd HTTP/1.1
      Accept: application/vnd.api+json

Response 

      HTTP/1.1 200 OK
      Content-Type: application/vnd.api+json
      
      {
        "data": {
          "id": "1737042d-3151-4fa4-bdb8-5a87a8f2d6fd",
          "type": "asset-uploads",
          "links": {
            "self": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd"
          }
          "attributes": {
            "file-name": "logo.png",
            "key": "c97d0973-8a5c-4300-a70c-58e837c8c90c/1483810832535/logo.png",
            "content-type": "image/png",
            "file-size": 22366,
            "user-agent": "My Live Editor API Client v1",
            "status": "finished",
            "error-message": null,
            "created-at": "2012-04-23T18:25:43.511Z",
            "updated-at": "2012-04-23T18:25:43.511Z"
          },
          "relationships": {
            "asset": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/relationships/asset"
                "related": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/asset"
              },
              "data": {
                "type": "assets",
                "id": "1fbf1d3e-ce8e-4a3e-aeae-f0fccf93513d"
              }
            },
            "asset-file": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/relationships/asset-file"
                "related": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/asset-file"
              },
              "data": {
                "type": "asset-images",
                "id": "e2b01923-12a6-497a-88cc-b7fdd8a6e0e8"
              }
            }
          }
        }
      }

Example error asset upload

An asset upload with a status of error will also include an error-message explaining what went wrong:

Request 

      GET https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd HTTP/1.1
      Accept: application/vnd.api+json

Response 

      HTTP/1.1 200 OK
      Content-Type: application/vnd.api+json
      
      {
        "data": {
          "id": "1737042d-3151-4fa4-bdb8-5a87a8f2d6fd",
          "type": "asset-uploads",
          "links": {
            "self": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd"
          }
          "attributes": {
            "file-name": "logo.png",
            "key": "c97d0973-8a5c-4300-a70c-58e837c8c90c/1483810832535/logo.png",
            "content-type": "image/png",
            "file-size": 22366,
            "user-agent": "My Live Editor API Client v1",
            "status": "error",
            "error-message": "Unrecognized image format",
            "created-at": "2012-04-23T18:25:43.511Z",
            "updated-at": "2012-04-23T18:25:43.511Z"
          },
          "relationships": {
            "asset": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/relationships/asset"
                "related": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/asset"
              },
              "data": null,
            },
            "asset-file": {
              "links": {
                "self": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/relationships/asset-file"
                "related": "https://coffee.api.liveeditorapp.com/asset-uploads/1737042d-3151-4fa4-bdb8-5a87a8f2d6fd/asset-file"
              },
              "data": null
            }
          }
        }
      }

See the Asset Upload Data Model for more information about the information provided by the Asset Uploads endpoint.

Related