Best practices: Object shapes

Follow recommended best practices for using objects in action cards.

Avoid designing an action card that requires a JSON object as an input value, and it's preferable not to add output fields that return single objects. If an output field returns only one object at a time and the keys for the object are known, then add a set of output fields to return each of the values within the object. Otherwise, you will likely force a user of the action card to implement additional cards in their flow to parse the JSON object that is returned from the action card.

This is an example of an object that is returned by an API:

Copy

{
  "user": {
    "name": {
      "first": "Bill",
      "last": "Lumbergh"
    },
    "email": "bill@initech.net",
    "address": {
      "street1": "123 Corporate Drive",
      "street2": "Suite 45",
      "city": "Middle",
      "state": "MI",
      "zip": "67890",
      "country": "US"
    }
  }
}

It is recommended to return these nested attributes as top-level fields using headers to group them.

Copy

[
  {
    "name": "User",
    "attributes": [
      {
        "name": "First Name",
        "type": "string"
      },
      {
        "name": "Last Name",
        "type": "string"
      },
      {
        "name": "Email",
        "type": "string"
      }
    ]
  },
  {
    "name": "Address",
    "attributes": [
      {
        "name": "Street 1",
        "type": "string"
      },
      {
        "name": "Street 2",
        "type": "string"
      },
      {
        "name": "City",
        "type": "string"
      },
      {
        "name": "State",
        "type": "string"
      },
      {
        "name": "Zipcode",
        "type": "string"
      },
      {
        "name": "Country",
        "type": "string"
      }
    ]
  }
]

A common use case when using objects as outputs is when an action card returns a collection of items such as a list of records from a collaboration or ticketing app. In such an object, make sure to include a schema for the attributes of that object. Make the object structure as flat as possible in order to reduce the potential for needing other action cards to read data from the same API endpoint.

Copy

[
  {
    "name": "Result",
    "attributes": [
      {
        "name": "Tags",
        "type": "object",
        "collection": true,
        "attributes": [
          {
            "name": "Tag Name",
            "type": "string"
          },
          {
            "name": "Tag ID",
            "type": "string"
          },
          {
            "name": "Tag Color",
            "type": "string"
          }
        ]
      }
    ]
  }
]

Best practices: Object shapes

Related topics