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