Response Format Customisation

Some APIs that return data allow you to extend and customise the response format. This is done by defining a object structure, and passing that template object as part of your query. If you do not provide a response format the API will return a default set of values. Overall this lets you request exactly what you require, including, in some cases, related sub data, such as requesting a customer returning the 5 most recent sales.

Quick Example
{
    a: "fd1.data",
    v: { table: "products" },
    qo: {
        pid: true,
        "Current-Price": price,
        "SupplierID" : "spid" ,
        "SupplierName": "spid.name"
        
        "SupplierDetails": {
            name: "spid.name",
            email: "spid.email"
        }
        "One_Image": "images[best].url"
    }
}

Sample Output
{
    r: "fd1.data",
    data: {
      rows: [ {
          pid: 4724,
          "Current-Price": 10.95,
          "SupplierID": 42,
          "SupplierName": "Acme Supplies",
          "SupplierDetails": {
            name: "Acme Supplies",
            email: "orders@acme.example.com"
          }
          "One_Image": "https://example.com/p4724.png"
        } ]
    }
}

Tip: Mouse over the JSON definition.
A slightly longer explanation of the above is to consider that everything is stored in a "table" or spreadsheet conceptually. So there would be a table of products that might look like this

Products.

pid	description	price	Price ExTax	supplier id aka spid	alternative spid	department id	Is Raw	Health Standard	Harmonized Code	....
4724	Sparkling Water	10.95	9.875	42	157	19	0	AS 441	123456	more data...

The "qo" request, is simply extracting the columns for each row and placing into the output object. Except when we get to supplier; the product only has a reference, which is an id into the suppliers table.

Suppliers.

spid	name	phone	email	city	....
42	Acme Supplies	09 123 4567	orders@acme.example.com	Suva	more data...
157	Adams & Collier	02 9876 3456	xyz@ac.com	Tullamarine	more data...

The "SupplierID": "spid" in the qo means, for the current product row, extract the "spid" field and return that.

The "SupplierName": "spid.name" means, extract the "spid" for the current row. We know that id refers to a supplier, so lookup the corresponding supplier row, and return the name field.

The "SupplierDetails": { name: "spid.name", email: "spid.email" } means the same thing as the two rows above, but in the case it has been placed in a sub object. This kicks in when returning an array of sub values, such as all items on a sale.

The "One_Image": "images[best].url" is doing the same operation. Select the "images" table. Reduce that table and select the "best" (single) image for this product, and return the URL. "best" is a selection keyword and has meaning to images. Consider it to be like an SQL where clause reducing the rows. In this case, it will probably select the rank=1 image

Images.

pid	ImageId	url	licence	rank	camera angle	....
4724	NJ92183.2	https://example.com/p4724.png	private	1	front oblique	more data...
4724	KNJ92BCW	https://AWS-bucket/SKBOF$Hjnvheh46.jpeg	supplier	8	front	more data...

Example. A normal request for a purchase order is thus

POST /fd1/purchaseorders/get_purchaseorder_header
{
  "a": "purchaseorders.get_purchaseorder_header",
  "q": {
    "cust_ponum": 12345
  }
}

Or the GET equivalent, (GET /fd1/purchaseorders/get_purchaseorder_header?cust_ponum=12345)

This instructs Fieldpine to return the default details about purchase order 12345. Invariably this will always be too much or too little. You can therefore add a "qo" object that defines what you want to receive and how it is structured

POST /fd1/purchaseorders/get_purchaseorder_header
{
  "a": "purchaseorders.get_purchaseorder_header",
  "q": {
    "cust_ponum": 12345
  },
  "qo": {
    "poid": true,
    "AnotherNameForId": "poid",

    "entrydt": true,
    "completeddt": true,
    "theSupplier": {
        "name": "supplier.name",
        "phone":  "supplier.phone"
    },
    "No_of_lines_on_PO": "poline._count"
  }
}

TL;DR

You don't really need to learn this for simple use cases, just do this

1. Define a JSON object containing the fields you want.
   • Use "name": true for what you want
   • If you want values in a child object, create the object and continue to put "name": true
2. Use the FD1 documentation to find the valid field names. Cut/paste them.
3. Keep in mind that when you issue a query - the server is placing you on a "concept" (thing, object, row in database). That concept has direct attributes (fields, values, members), and also indirect values (derived, information, related tables, parent/child data).
   So you are looking for the direct and indirect fields for each concept
4. You can go move concepts a little bit, but dont expect to go from sale » salelines » products » all-customers-that-ever-bought-that » city
   Basically, too much load on the server, and we ask you do it in a couple of queries instead.

Simple Example, starting from a "sale"

... qo: {
    saleid: true,                                   // Return current sales id#
    total_extax: true,                              // Return total value of this sale, exclusive  tax
    customer: {
        id: "sale.cid",                             // What is the customers id# (if any)
        email: "customer.email",                    // Lets get their email too
        totalsalecount: "customer.sales._count"     // Can we also get the total number of sales this customer has ever made
    }
}

Definition

• A qo definition consists of a valid JSON object
• Member names:
  1. Must start with a letter
  2. May only contain A-Z, a-z, 0-9, underscore.
  3. All other values are reserved
• A member name of * (star) means all default fields. This is not normally required as it is present by default
  eg
  { "*": true }
• A member name that starts with underscore indicates a control directive. These members are not included in the response. This permits specific controls to be passed to the server
  eg
  { "_order": "date" }
• If the value is "true", then the corresponding concept field is included in the response.
  eg
  { poid: true }
  Include direct field poid in response
• If the value is "false", then the corresponding concept field can be omitted from the response. This is a indicator to the server and the field may still be returned.
  eg
  { poid: false }
  Poid may be excluded from response.
• If the value is a string, and matches a valid direct or indirect field the value is retrieved and returned
  eg
  { "StoreSpecificID": "poid" }
  return direct field poid in field "StoreSpecificID"
  { "StoreSpecificID": 12345 }
• If the value is an object then:
  1. The member name starts a new output object, and all definitions are processed.
     eg
     {
     "poid": true,
     "childobject": { "poid": true }
     }
     will result in
     {
     "poid": 12345,
     "childobject" : { "poid": 12345}
     }