Retrieving Data
Retrieving individual records
Individual records could be retrieved using either the Pepperi InternalID or the ExternalID usually provided by your back-end system. e.g: you can retrieve a specific Sales Order using /transactions/787654 or /transactions/externalid/SO3456.
Retrieving record lists
Record lists are retrieved using the GET Method of each and every resource.
Pagination
Retrieving large sets of data requires iterating over the pages, either by using the number of pages provided in the X-Pepperi-Total-Pages Response Header when applying include_count=true on the query parameters, or by iterating until you get a page with an empty list.
Pagination Query Parameters
-
page– index of page retrieved. page_size– number of records per page – default number is 100 , and the limit is 250.
Filtering , Sorting and other data fetching features
The following query parameters are available for every GET request :
- where
- Date filter syntax –
where=ActionDateTime >='2016-01-15T14:00:00Z' AND ActionDateTime <= '2017-01-15T14:00:00Z' - Supports IN syntax –
where=MainCategoryID IN('Toys','Watches','Cars') - Supports AND , OR syntax –
where=(Price > 100 AND Price < 250) OR MainCategoryID = 'Toys' - Null values filter syntax –
where=Agent is not null
- Date filter syntax –
- order_by
- Supports multiple sorting fields – e.g:
order_by=AgentName DESC, ActionDateTime ASC
- Supports multiple sorting fields – e.g:
- fields
- Supports specifying fields to reduce the amount of data retrieved and improve performance. e.g:
fields=ExternalID,ActionDateTime,GrandTotal - Supports “bubble-up” field specification – fetching fields of parent resources all the way up using <ParentField>.<Field> syntax – an important feature to reduce number of calls to the API and improve performance. e.g:
GET /transaction_lines?fields=Transaction.ActionDateTime,Transaction.Agent.Name,Item.Name,UnitsQuantity,UnitPriceAfterDiscount.
- Supports specifying fields to reduce the amount of data retrieved and improve performance. e.g:
- include_deleted
- Includes records in Hidden status. In Pepperi API any record you perform DELETE on is not really deleted but merely changes its status to Hidden – so that you may use this feature to retrieve records from Pepperi “Recycle Bin”.
- include_nested
- Includes one-to-many nested objects, such as Transaction Lines within Transaction or list of Users assigned to Account.
- full_mode
- Includes all one-to-one parent object fields. e.g : by default all parent objects are retrieved with InternalID and ExternalID only, so that if you request GET transactions you will get the Account InternalID and ExternalID, if you want to get the Account Address as well you will need to specify in the transactions GET
full_mode=true. PLEASE NOTE: This feature is primarily made for retrieving single record or for you to view the data and understand what are the available fields – once you know what fields you need – please specify them in the fields query parameter explained above – using full_mode in production for multiple records request may result in poor performance.
- Includes all one-to-one parent object fields. e.g : by default all parent objects are retrieved with InternalID and ExternalID only, so that if you request GET transactions you will get the Account InternalID and ExternalID, if you want to get the Account Address as well you will need to specify in the transactions GET
Retrieving records count only
Each GET request to Pepperi with include_count=true as a query parameter will return 2 Custom Response Headers: X-Pepperi-Total-Records and X-Pepperi-Total-Pages , so that if you want to query all transactions made in the last 30 days , you can use the “where” filter and fetch these headers with the first page or record only.