Adjust Number of Fields to be Returned from a Request

Owned by Karl-André Dalby
Last updated: Nov 17, 2017 by Dataloy (Unlicensed)
13 min read

Short Description

From version 2.10 it is possible to adjust the number of fields that are to be returned from a resource. It's possible to both increase and decrease the number of fields from the default view. So if only field A and B from a resource is needed and the other X number of fields can be ignored, it can be specified in the header of the request. This will reduce the overhead of data transferred and improve performance. If more fields are needed in one request, to avoid making a second request to get all the data that is needed, this can also be done. So if fields A, B and C are returned in the default view, but also field D is needed, this can be specified in the header.

Chapter Contents: 

Long Description

Decrease Number of Fields

Retrieving data from a resource may provide more information than needed. Fields with data to be returned can be specified by first adding a header field and then specifying the fields to be returned in the header field value. The header field value is specified as a json message following same structure as the resource structure that is used when making the request. This enables fields to be specified in main- and sub-objects.  

The examples listed illustrates how it is used for a business partner. The procedure is, however, the same for all resources. The key and self attribute will always be returned, but the number of displayed/hidden fields can be customized.

Business Partner without any field restriction will result in (to view example, click expand):

Default response from BusinessPartner 
{
  "businessPartnerName": "Dataloy Chartering",
  "businessPartnerSort": "DATALOYCHARTERING",
  "businessPartnerCode": "61210",
  "individuals": [],
  "codeProperty": "businessPartnerCode",
  "contactInfo": [
    {
      "phoneNo": "55360300",
      "mobileNo": null,
      "faxNo": null,
      "telexNo": null,
      "email": "sales@dataloy.com",
      "self": "http://localhost:8080/ws/rest/ContactInfo/231881070",
      "key": 231881070
    }
  ],
  "addresses": [
    {
      "address1": "Halfdan Kjerulfs gate 4",
      "address2": null,
      "address3": null,
      "postalCode": "5017",
      "city": "Bergen",
      "countryCode": "NO",
      "self": "http://localhost:8080/ws/rest/Address/231881068",
      "key": 231881068
    }
  ],
  "bankAccounts": [
    {
      "key": 231881008,
      "self": "http://localhost:8080/ws/rest/BankAccount/231881008",
      "bankAccountNo": "1234567890",
      "favouringCompany": null,
      "iban": null,
      "bank": {
        "key": 231881006,
        "self": "http://localhost:8080/ws/rest/Bank/231881006",
        "countryCode": null,
        "abaNumber": null,
        "bankName": "DNB",
        "chip": null,
        "swiftAddress": null
      }
    }
  ],
  "createdDate": "2016-02-19T14:24:48",
  "modifiedDate": "2016-02-19T14:45:14",
  "createdById": 999999,
  "isInterCompany": false,
  "businessUnit": {
    "key": 231881004,
    "self": "http://localhost:8080/ws/rest/BusinessUnit/231881004",
    "businessUnitCode": "DL",
    "businessUnitName": "Dataloy"
  },
  "bankAccount": {
    "key": 231881008,
    "self": "http://localhost:8080/ws/rest/BankAccount/231881008",
    "bankAccountNo": "1234567890",
    "favouringCompany": null,
    "iban": null,
    "bank": {
      "key": 231881006,
      "self": "http://localhost:8080/ws/rest/Bank/231881006",
      "countryCode": null,
      "abaNumber": null,
      "bankName": "DNB",
      "chip": null,
      "swiftAddress": null
    }
  },
  "paymentTerms": {
    "key": 1771161,
    "self": "http://localhost:8080/ws/rest/PaymentTerms/1771161",
    "paymentTermsCode": "5D"
  },
  "baselineTerm": {
    "key": 15894046,
    "self": "http://localhost:8080/ws/rest/BaselineTerm/15894046",
    "baselineTermCode": "UCD",
    "baselineTermDesc": "upon completion of discharge"
  },
  "payee": null,
  "businessPartnerName2": null,
  "companyRegistrationNo": "1234567890",
  "isTotalCommissionPayable": false,
  "maxAdvancePaymentPercent": 100,
  "vatNumber": "1234567890",
  "businessPartnerLink": null,
  "businessPartnerType": {
    "businessPartnerType": "C",
    "businessPartnerTypeDesc": "Charterer",
    "key": 1000032,
    "self": "http://localhost:8080/ws/rest/BusinessPartnerType/1000032"
  },
  "companyBankAccount": null,
  "self": "http://localhost:8080/ws/rest/BusinessPartner/231881010",
  "remarks": [],
  "key": 231881010
}
Examples

1. Return Business Partner name only:

fields: {"businessPartnerName":"*"}

{
  "businessPartnerName": "Dataloy Chartering",
  "self": "http://localhost:8080/ws/rest/BusinessPartner/231881010",
  "key": 231881010
}

2. Return address1 only:

fields: {"addresses": {"address1":"*"}}

 

Note that addresses is an array, but for the fields value it should be treated as a field, so do not include [ ]

{
  "addresses": [
    {
      "address1": "Halfdan Kjerulfs gate 4",
      "self": "http://localhost:8080/ws/rest/Address/231881068",
      "key": 231881068
    }
  ],
  "self": "http://localhost:8080/ws/rest/BusinessPartner/231881010",
  "key": 231881010
}

3. Return Business Partner name and address1:

fields: {"businessPartnerName":"*", "addresses":{"address1":"*"}}

{
  "businessPartnerName": "Dataloy Chartering",
  "addresses": [
    {
      "address1": "Halfdan Kjerulfs gate 4",
      "self": "http://localhost:8080/ws/rest/Address/231881068",
      "key": 231881068
    }
  ],
  "self": "http://localhost:8080/ws/rest/BusinessPartner/231881010",
  "key": 231881010
}

Increase Number of Fields

To avoid the need of a second request when the amount of data to be retrieved is too much for a single request to be sufficient two header fields can be added to extend the default view for the requested resource. This option is available main- and sub-objects (no limit of depth into hierarchy).

Examples

1. Add voyage currency to Business Unit in Business Partner resource (field is not visible when Business Unit is a sub-object).

view: YES
fields:  {"businessUnit":{"voyageCurrency":"*"}}

{
  "businessPartnerName": "Dataloy Chartering",
  "businessPartnerSort": "DATALOYCHARTERING",
  "businessPartnerCode": "61210",
  "addresses": [
    {
      "address1": "Halfdan Kjerulfs gate 4",
      "address2": null,
      "address3": null,
      "postalCode": "5017",
      "city": "Bergen",
      "countryCode": "NO",
      "self": "http://localhost:8080/ws/rest/Address/231881068",
      "key": 231881068
    }
  ],
  "codeProperty": "businessPartnerCode",
  "contactInfo": [
    {
      "phoneNo": "55360300",
      "mobileNo": null,
      "faxNo": null,
      "telexNo": null,
      "self": "http://localhost:8080/ws/rest/ContactInfo/231881070",
      "key": 231881070
    }
  ],
  "individuals": [],
  "bankAccounts": [
    {
      "key": 231881008,
      "self": "http://localhost:8080/ws/rest/BankAccount/231881008",
      "bankAccountNo": "1234567890",
      "favouringCompany": null,
      "iban": null,
      "bank": {
        "key": 231881006,
        "self": "http://localhost:8080/ws/rest/Bank/231881006",
        "countryCode": null,
        "abaNumber": null,
        "bankName": "DNB",
        "chip": null,
        "swiftAddress": null
      }
    }
  ],
  "bankAccount": {
    "key": 231881008,
    "self": "http://localhost:8080/ws/rest/BankAccount/231881008",
    "bankAccountNo": "1234567890",
    "favouringCompany": null,
    "iban": null,
    "bank": {
      "key": 231881006,
      "self": "http://localhost:8080/ws/rest/Bank/231881006",
      "countryCode": null,
      "abaNumber": null,
      "bankName": "DNB",
      "chip": null,
      "swiftAddress": null
    }
  },
  "paymentTerms": {
    "key": 1771161,
    "self": "http://localhost:8080/ws/rest/PaymentTerms/1771161",
    "paymentTermsCode": "5D"
  },
  "baselineTerm": {
    "key": 15894046,
    "self": "http://localhost:8080/ws/rest/BaselineTerm/15894046",
    "baselineTermCode": "UCD",
    "baselineTermDesc": "upon completion of discharge"
  },
  "isInterCompany": false,
  "businessUnit": {
    "key": 231881004,
    "self": "http://localhost:8080/ws/rest/BusinessUnit/231881004",
    "businessUnitCode": "DL",
    "businessUnitName": "Dataloy",
    "voyageCurrency": "USD"
  },
  "businessPartnerName2": null,
  "companyRegistrationNo": "1234567890",
  "isTotalCommissionPayable": false,
  "maxAdvancePaymentPercent": 100,
  "vatNumber": "1234567890",
  "businessPartnerType": {
    "businessPartnerType": "C",
    "businessPartnerTypeDesc": "Charterer",
    "key": 1000032,
    "self": "http://localhost:8080/ws/rest/BusinessPartnerType/1000032"
  },
  "companyBankAccount": null,
  "self": "http://localhost:8080/ws/rest/BusinessPartner/231881010",
  "key": 231881010
}

2. Add voyage currency to Business Unit and country name for address in Business Partner resource:

view: YES
fields:  {"businessUnit":{"voyageCurrency":"*"},"addresses":{"country":{"countryName":"*"}}}

{
  "businessPartnerName": "Dataloy Chartering",
  "businessPartnerSort": "DATALOYCHARTERING",
  "businessPartnerCode": "61210",
  "addresses": [
    {
      "address1": "Halfdan Kjerulfs gate 4",
      "address2": null,
      "address3": null,
      "postalCode": "5017",
      "city": "Bergen",
      "country": {
        "countryName": "Norway",
        "key": 410154,
        "self": "http://localhost:8080/ws/rest/Country/410154"
      },
      "countryCode": "NO",
      "self": "http://localhost:8080/ws/rest/Address/231881068",
      "key": 231881068
    }
  ],
  "codeProperty": "businessPartnerCode",
  "contactInfo": [
    {
      "phoneNo": "55360300",
      "mobileNo": null,
      "faxNo": null,
      "telexNo": null,
      "self": "http://localhost:8080/ws/rest/ContactInfo/231881070",
      "key": 231881070
    }
  ],
  "individuals": [],
  "bankAccounts": [
    {
      "key": 231881008,
      "self": "http://localhost:8080/ws/rest/BankAccount/231881008",
      "bankAccountNo": "1234567890",
      "favouringCompany": null,
      "iban": null,
      "bank": {
        "key": 231881006,
        "self": "http://localhost:8080/ws/rest/Bank/231881006",
        "countryCode": null,
        "abaNumber": null,
        "bankName": "DNB",
        "chip": null,
        "swiftAddress": null
      }
    }
  ],
  "bankAccount": {
    "key": 231881008,
    "self": "http://localhost:8080/ws/rest/BankAccount/231881008",
    "bankAccountNo": "1234567890",
    "favouringCompany": null,
    "iban": null,
    "bank": {
      "key": 231881006,
      "self": "http://localhost:8080/ws/rest/Bank/231881006",
      "countryCode": null,
      "abaNumber": null,
      "bankName": "DNB",
      "chip": null,
      "swiftAddress": null
    }
  },
  "paymentTerms": {
    "key": 1771161,
    "self": "http://localhost:8080/ws/rest/PaymentTerms/1771161",
    "paymentTermsCode": "5D"
  },
  "baselineTerm": {
    "key": 15894046,
    "self": "http://localhost:8080/ws/rest/BaselineTerm/15894046",
    "baselineTermCode": "UCD",
    "baselineTermDesc": "upon completion of discharge"
  },
  "isInterCompany": false,
  "businessUnit": {
    "key": 231881004,
    "self": "http://localhost:8080/ws/rest/BusinessUnit/231881004",
    "businessUnitCode": "DL",
    "businessUnitName": "Dataloy",
    "voyageCurrency": "USD"
  },
  "businessPartnerName2": null,
  "companyRegistrationNo": "1234567890",
  "isTotalCommissionPayable": false,
  "maxAdvancePaymentPercent": 100,
  "vatNumber": "1234567890",
  "businessPartnerType": {
    "businessPartnerType": "C",
    "businessPartnerTypeDesc": "Charterer",
    "key": 1000032,
    "self": "http://localhost:8080/ws/rest/BusinessPartnerType/1000032"
  },
  "companyBankAccount": null,
  "self": "http://localhost:8080/ws/rest/BusinessPartner/231881010",
  "key": 231881010
}

 

4. Show remark for addresses on BusinessPartner. This can be applied to any sub object. It is also possible to add the remark itself, but be very careful if doing this. Remark has datatype CLOB which can store up to 4GB of data.

view: YES
{"addresses":{"remarks":{"remarkTitle":"*", "source":"*"}}}

{
  "businessPartnerName": "Dataloy Chartering",
  "businessPartnerSort": "DATALOYCHARTERING",
  "businessPartnerCode": "61210",
  "individuals": [],
  "codeProperty": "businessPartnerCode",
  "contactInfo": [
    {
      "phoneNo": "55360300",
      "mobileNo": null,
      "faxNo": null,
      "telexNo": null,
      "email": "sales@dataloy.com",
      "self": "http://localhost:8080/ws/rest/ContactInfo/231881070",
      "key": 231881070
    }
  ],
  "addresses": [
    {
      "address1": "Halfdan Kjerulfs gate 4",
      "address2": null,
      "address3": null,
      "postalCode": "5017",
      "city": "Bergen",
      "countryCode": "NO",
      "self": "http://localhost:8080/ws/rest/Address/231881068",
      "remarks": [
        {
          "remarkTitle": "Remark for Dataloy Address",
          "key": 230111490,
          "self": "http://localhost:8080/ws/rest/Remark/230111490",
          "source": 20011677
        }
      ],
      "key": 231881068
    }
  ],
  "bankAccounts": [
    {
      "key": 231881008,
      "self": "http://localhost:8080/ws/rest/BankAccount/231881008",
      "bankAccountNo": "1234567890",
      "favouringCompany": null,
      "iban": null,
      "bank": {
        "key": 231881006,
        "self": "http://localhost:8080/ws/rest/Bank/231881006",
        "countryCode": null,
        "abaNumber": null,
        "bankName": "DNB",
        "chip": null,
        "swiftAddress": null
      }
    }
  ],
  "createdDate": "2016-02-19T14:24:48",
  "modifiedDate": "2016-02-19T14:45:14",
  "createdById": 999999,
  "isInterCompany": false,
  "businessUnit": {
    "key": 231881004,
    "self": "http://localhost:8080/ws/rest/BusinessUnit/231881004",
    "businessUnitCode": "DL",
    "businessUnitName": "Dataloy"
  },
  "bankAccount": {
    "key": 231881008,
    "self": "http://localhost:8080/ws/rest/BankAccount/231881008",
    "bankAccountNo": "1234567890",
    "favouringCompany": null,
    "iban": null,
    "bank": {
      "key": 231881006,
      "self": "http://localhost:8080/ws/rest/Bank/231881006",
      "countryCode": null,
      "abaNumber": null,
      "bankName": "DNB",
      "chip": null,
      "swiftAddress": null
    }
  },
  "paymentTerms": {
    "key": 1771161,
    "self": "http://localhost:8080/ws/rest/PaymentTerms/1771161",
    "paymentTermsCode": "5D"
  },
  "baselineTerm": {
    "key": 15894046,
    "self": "http://localhost:8080/ws/rest/BaselineTerm/15894046",
    "baselineTermCode": "UCD",
    "baselineTermDesc": "upon completion of discharge"
  },
  "payee": null,
  "businessPartnerName2": null,
  "companyRegistrationNo": "1234567890",
  "isTotalCommissionPayable": false,
  "maxAdvancePaymentPercent": 100,
  "vatNumber": "1234567890",
  "businessPartnerLink": null,
  "businessPartnerType": {
    "businessPartnerType": "C",
    "businessPartnerTypeDesc": "Charterer",
    "key": 1000032,
    "self": "http://localhost:8080/ws/rest/BusinessPartnerType/1000032"
  },
  "companyBankAccount": null,
  "self": "http://localhost:8080/ws/rest/BusinessPartner/231881010",
  "remarks": [],
  "key": 231881010
}

 

5. Add all Business Unit fields in Business Partner resource. If adding many fields, the header string will be long, use "all" instead to increase the length:

view: YES
fields:  {"businessUnit":{"all":"*"}}

{
  "businessPartnerName": "Dataloy Chartering",
  "businessPartnerSort": "DATALOYCHARTERING",
  "businessPartnerCode": "61210",
  "individuals": [],
  "codeProperty": "businessPartnerCode",
  "contactInfo": [
    {
      "phoneNo": "55360300",
      "mobileNo": null,
      "faxNo": null,
      "telexNo": null,
      "email": "sales@dataloy.com",
      "self": "http://localhost:8080/ws/rest/ContactInfo/231881070",
      "key": 231881070
    }
  ],
  "addresses": [
    {
      "address1": "Halfdan Kjerulfs gate 4",
      "address2": null,
      "address3": null,
      "postalCode": "5017",
      "city": "Bergen",
      "countryCode": "NO",
      "self": "http://localhost:8080/ws/rest/Address/231881068",
      "remarks": [
        {
          "remarkTitle": "Remark for Dataloy Address",
          "key": 230111490,
          "self": "http://localhost:8080/ws/rest/Remark/230111490",
          "source": 20011677
        }
      ],
      "key": 231881068
    }
  ],
  "bankAccounts": [
    {
      "key": 231881008,
      "self": "http://localhost:8080/ws/rest/BankAccount/231881008",
      "bankAccountNo": "1234567890",
      "favouringCompany": null,
      "iban": null,
      "bank": {
        "key": 231881006,
        "self": "http://localhost:8080/ws/rest/Bank/231881006",
        "countryCode": null,
        "abaNumber": null,
        "bankName": "DNB",
        "chip": null,
        "swiftAddress": null
      }
    }
  ],
  "createdDate": "2016-02-19T14:24:48",
  "modifiedDate": "2016-02-19T14:45:14",
  "createdById": 999999,
  "isInterCompany": false,
  "businessUnit": {
    "key": 231881004,
    "self": "http://localhost:8080/ws/rest/BusinessUnit/231881004",
    "codeProperty":" businessUnitCode,
	"voyageCurrency": "USD",
    "businessUnitCode": "DL",
    "businessUnitName": "Dataloy",
    "remarks":[]
  },
  "bankAccount": {
    "key": 231881008,
    "self": "http://localhost:8080/ws/rest/BankAccount/231881008",
    "bankAccountNo": "1234567890",
    "favouringCompany": null,
    "iban": null,
    "bank": {
      "key": 231881006,
      "self": "http://localhost:8080/ws/rest/Bank/231881006",
      "countryCode": null,
      "abaNumber": null,
      "bankName": "DNB",
      "chip": null,
      "swiftAddress": null
    }
  },
  "paymentTerms": {
    "key": 1771161,
    "self": "http://localhost:8080/ws/rest/PaymentTerms/1771161",
    "paymentTermsCode": "5D"
  },
  "baselineTerm": {
    "key": 15894046,
    "self": "http://localhost:8080/ws/rest/BaselineTerm/15894046",
    "baselineTermCode": "UCD",
    "baselineTermDesc": "upon completion of discharge"
  },
  "payee": null,
  "businessPartnerName2": null,
  "companyRegistrationNo": "1234567890",
  "isTotalCommissionPayable": false,
  "maxAdvancePaymentPercent": 100,
  "vatNumber": "1234567890",
  "businessPartnerLink": null,
  "businessPartnerType": {
    "businessPartnerType": "C",
    "businessPartnerTypeDesc": "Charterer",
    "key": 1000032,
    "self": "http://localhost:8080/ws/rest/BusinessPartnerType/1000032"
  },
  "companyBankAccount": null,
  "self": "http://localhost:8080/ws/rest/BusinessPartner/231881010",
  "remarks": [],
  "key": 231881010
}


Top
Back

Related Content

 Expand to see related content

Unknown macro: {dynamiccontentbylabel}