Metadata APIs

Overview

If you're looking to dynamically render a list of fields required for each endpoint in Unified API, look no further than our Metadata APIs.

Use Case

To better understand when Metadata APIs can come in handy, consider this use case: you want to integrate with a number of Accounting systems like NetSuite, Quickbooks, and SAP. While Unified API offers a common format to interact with all these applications, perhaps you want to allow your end user to map data they want to sync. Alloy Unified API offers metadata APIs to make it easy to do just this.

Listing Operations for an App

To list all possible endpoints (also known as operations) available for an app, hit the GET List Operations for App endpoint. You can find a sample request and response below.

Sample Request

curl --request GET \
     --url https://embedded.runalloy.com/2024-03/one/metadata/operations?app=shopify \
     --header 'Authorization: bearer YOUR_API_KEY' \
     --header 'accept: application/json'

Note that you will need to supply an app in the query parameters. You can find a list of internal app names by calling the GET List Apps endpoint.

Sample Response

{
  "operations": {
    "customer": [
      "listCustomers",
      "createCustomer",
      "updateCustomer",
      "deleteCustomer",
      "getCustomer"
    ],
    "order": [
      "listOrders",
      "createOrder",
      "updateOrder",
      "deleteOrder",
      "getOrder"
    ],
    "product": [
      "listProducts",
      "createProduct",
      "updateProduct",
      "deleteProduct",
      "getProduct"
    ],
    "variant": [
      "listVariants",
      "createVariant",
      "updateVariant",
      "deleteVariant",
      "getVariant"
    ],
    "fulfillment": [
      "listFulfillments",
      "getFulfillment"
    ]
  }
}

This endpoint returns a list of possible operations for Shopify.

Listing Fields for an Operation

Now that we've returned the list of operations for Shopify, we can return a list of fields for any operation. Let's take a look at how we'd do this for the createCustomer operation.

Sample Request

curl --request GET \
     --url 'https://embedded.runalloy.com/2024-03/one/metadata/fields?app=shopify&operation=createCustomer' \
     --header 'Authorization: bearer YOUR_API_KEY' \
     --header 'accept: application/json'

Sample Response

{
    "fields": [
        {
            "name": "firstName",
            "type": "string",
            "description": "First Name",
            "required": true
        },
        {
            "name": "lastName",
            "type": "string",
            "description": "Last Name",
            "required": true
        },
        {
            "name": "email",
            "type": "string",
            "description": "Email",
            "required": true
        },
        {
            "name": "phone",
            "type": "string",
            "description": "Phone",
            "required": false
        },
        {
            "name": "remoteFields",
            "type": "object",
            "description": "Remote Fields",
            "required": false
        }
    ]
}

Wrapping Up

In this article, we took a look at how to call the Metadata APIs to display operation-specific field data.