ColdFusion REST with Axios: Asynchronous Data Passing - JessicaOPRD/docs GitHub Wiki

Note: I think it's ideal to use the HTTP status code in the response header to determine success/failure.

POST multipart/form-data form using FormData native JavaScript object

🟢 Fairly simple to setup

🟢 Can type check individual form arguments

🟡 Ideal for simple arguments

🔴 FormData seems best choice only if passing file data, too

🔴 Cannot require individual form arguments, but can set default

🔴 ☠ Difficult to re-use function outside of POST context or REST endpoint

Client

async onSave() {
  const volunteerId = 22025

  const pet = new FormData()
  pet.append('description', 'Penelope')
  pet.append('type', 'dog')

  const { data } = await this.$api.post(
    `volunteers/${volunteerId}/pets`,
    pet
  )

  console.log(data)
}

Server

remote struct function addPet(
  required numeric volunteerId restArgSource="path"
)
  restPath="{volunteerId}/pets"
  httpMethod="POST"
  consumes="multipart/form-data"
{
  // Note requiring is not possible
  param name="form.description" type="string" default="";
  param name="form.type" type="string" default="";

  request.mailDeliveryUtil.debug({
    args = arguments,
    form = form
  });

  var r = {};

  r["success"] = false;

  return r;
}

POST all types and complex hierarchy as JSON

🟢 Very easy to setup

🟢 Very flexible and easy to support complex types

🔴 No ability to type check individual arguments aside from path

🔴 No ability to set default values as part of method signature

🟡 Requires "config" style argument passing for re-use outside of POST context or REST endpoint

Client

async onSave() {
  const volunteerId = 22025

  const pet = {
    description: 'Penelope',
    type: 'dog',
    favoriteThings: [
      'Eating poop',
      'Barking at neighbors',
      'Sleeping in laps'
    ]
  }

  const { data } = await this.$api.post(
    `volunteers/${volunteerId}/pets`,
    pet
  )

  console.log(data)
}

Server

remote struct function addPet(
  required numeric volunteerId restArgSource="path",
  required struct payload = {}
)
  restPath="{volunteerId}/pets"
  httpMethod="POST"
  consumes="application/json"
{
  request.mailDeliveryUtil.debug({
    args = arguments
  });

  var r = {};

  r["success"] = false;

  return r;
}

POST traditional application/x-www-form-urlencoded form data using a serializer

🔴 Awkward setup due to external serializer being required

🟡 Feels against REST philosophy to some degree

🟡 Ideal for simple data types

🟢 Ability to type check individual arguments

🟢 Ability to require individual arguments

🟢 Easy re-use outside of POST context or REST endpoint

Client

Note you will need to import a serializing library.

import qs from 'qs'

async onSave() {
  const volunteerId = 22025

  const pet = {
    description: 'Penelope',
    type: 'dog'
  }

  const { data } = await this.$api.post(
    `volunteers/${volunteerId}/pets`,
    qs.stringify(pet)
  )

  console.log(data)
}

Server

remote struct function addPet(
  required numeric volunteerId restArgSource="path",
  required string description restArgSource="form",
  required string type restArgSource="form"
)
  restPath="{volunteerId}/pets"
  httpMethod="POST"
  consumes="application/x-www-form-urlencoded"
{
  request.mailDeliveryUtil.debug({
    args = arguments
  });

  var r = {};

  r["success"] = false;

  return r;
}

POST with query parameters

🔴 Awkward setup due to Axios argument handling

🔴 Philosophically problematic to pass POST data as query parameters -- a POST ideally has a body of some sort

🔴 Passed parameters could become too long

🔴 Passed parameters could be seen as plain text in logs

🟡 Ideal for simple data types

🟢 Ability to type check individual arguments

🟢 Ability to require individual arguments

🟢 Easy re-use outside of POST context or REST endpoint

Client

async onSave() {
  const volunteerId = 22025

  const params = {
    description: 'Penelope',
    type: 'dog'
  }

  const { data } = await this.$api.post(
    `volunteers/${volunteerId}/pets`,
    undefined,
    { params }
  )

  console.log(data)
}

Server

remote struct function addPet(
  required numeric volunteerId restArgSource="path",
  required string description restArgSource="query",
  required string type restArgSource="query"
)
  restPath="{volunteerId}/pets"
  httpMethod="POST"
{
  request.mailDeliveryUtil.debug({
    args = arguments
  });

  var r = {};

  r["success"] = false;

  return r;
}