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.

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, (not shown here)

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}
     }