You can read existing records from a table.

See this example.

URL

Use a URL in the following form to invoke the API.

POST https://api.appsheet.com/api/v2/apps/{appId}/tables/{tableName}/Action where

  • {appId} specifies the GUID of the AppSheet application. You can obtain the {appId} from the Manage > Integrations > IN pane.
  • {tableName} specifies the name of the table to be read.

Body

The HTTP Body contains:

  1. The Action name “Find"”.
  2. Optional properties such as Locale, Location, and Timezone.
    The Locale is used when validating Date, Time, DateTime, Decimal, Percent, and Price data values. For example, when Locale is "en-US", date values must be entered in MM/DD/YYYY format. When Locale is "en-GB", date values must be entered in DD/MM/YYYY format.
  3. The optional Selector property.

Forms of Find

Read All Rows

You can omit the Selector property and not specify any input Rows. This will return all rows in the table.

{
"Action": "Find",
"Properties": {
   "Locale": "en-US",
   "Location": "47.623098, -122.330184",
   "Timezone": "Pacific Standard Time",
   "UserSettings": {
      "Option 1": "value1",
      "Option 2": "value2"
   }
},
"Rows": [
]
}


Read Selected Rows

In the Selector property, you can specify a Select expression that yields a list of record key values. The records identified by the key values are returned in the Rows response.

The Select expression can refer to a slice.

You can specify an OrderBy expression to control the sort order of the returned records. 

You can specify a Top expression to limit the number of returned rows.

{
"Action": "Find",
"Properties": {
   "Locale": "en-US",
   "Location": "47.623098, -122.330184",
   "Timezone": "Pacific Standard Time",
   "UserSettings": {
      "Option 1": "value1",
      "Option 2": "value2"
   }
},
"Rows": [
]
}


The Selector can take many forms including:

"Selector": "Filter(People, true)"
"Selector": "Filter(People, [Age] >= 21)"
"Selector": "Select(People[_ComputedKey], And([Age] >= 21, [State] = "CA"), true)"
"Selector": "OrderBy(Filter(People, [Age] >= 21), [LastName], true)"
"Selector": "Top(OrderBy(Filter(People, [Age] >= 21), [LastName], true), 10)"
"Selector": "Top(OrderBy(Select(People[_ComputedKey], And([Age] >= 21, [Date Hired] > "01/01/2016"), true), [LastName], false), 100)"


Read Input Rows

You can omit the Selector property and specify input Rows containing the key values of the records to be read. This will return all rows having matching key values from the table.

{
"Action": "Find",
"Properties": {
   "Locale": "en-US",
   "Location": "47.623098, -122.330184",
   "Timezone": "Pacific Standard Time",
   "UserSettings": {
      "Option 1": "value1",
      "Option 2": "value2"
   }
},
"Rows": [
{
"FirstName": "Jan",
"LastName": "Jones",
}
]
}

Security Filters

The Find is performed under the identity of the application owner by default. Your can override this by specifying the RunAsUserEmail property in the request properties.

Security Filters are applied when the Find is performed.

API Response Content

The API returns the rows in HTTP contents.

The returned records include all field values. This includes Virtual fields and field values computed by worksheet formulas.

{

  "Rows": [

{

"_RowNumber": 10,

"FirstName": "Jan",

"LastName": "Jones",

"Age": 33,

"Department": "Accounting",

"Street": "110 Beach Blvd",

"City": "Newport Beach",

"State": "CA",

"Zip": 92661,

"Home Phone": 4257868765,

"Fax": 4253214432,

"Date Hired": "10/31/2014",

"Arrived": "8:15:25",

"Departed": "18:30:33",

"Last Review": "08/31/2017 23:59:59",

"Rating": 0.9950,

"Salary": 3333.45,

"Image": "http://images6.fanpop.com/image/photos/36300000/Emilia-Clarke-image-emilia-clarke-36399128-460-276.jpg"

}

]

}

API Response HTTP Status Codes

The API returns the following HTTP status codes. 

  1. 200 Success
  2. 400 Bad Request
    a. The Application Access Key is missing.
    b. The AppId is missing.
    c. The Post body contains invalid data.
  3. 403 Forbidden
    a. The Web API is not enabled for this application.
    b. The Application Access Key is invalid.
  4. 404 Not Found
    a. The application specified by the AppId cannot be found.
  5. 500 Internal Server Error
    a. An unexpected error occurred.

When a Record is Read

  1. The record is retrieved based on the key values you specify.
  2. The record is returned in the HTTP content.

Row Having Key Not Found

See topic "Row Having Key Not Found" here.

Did this answer your question?