This tutorial walks you through creating your first Web API to retrieve a JSON-encoded list of records. The record we're going to use in this example is the entity-backed record from the Records Tutorial, but you can follow along with any record that you already have in your environment.

• To learn about web APIs and their configuration options, see Web APIs.
• To learn the basic steps involved with creating an API, see Creating Web APIs.
• To learn about web API authentication, see Web API Authentication.

Setup

Complete the Records Tutorial.

Create a record type constant

In order to retrieve record data (which you'll see later), we are going to use the queryrecord() expression function. This function requires a record type constant for one of its parameters. So before we build out our Web API we want to make sure that we have a record type constant that you can select.

1. In the application view of the Appian Tutorial application, click NEW > Constant.

2. In the Create Constant dialog, configure the following properties:

   Property	Description
   Create from Scratch	Leave selected.
   Name	Enter: AT_EMPLOYEE_RECORD
   Type	Select Record Type.
   Value	Select the Employee Directory.
   Save In	Use the picker to select the AT Rules & Constants folder.

3. Click CREATE.

Create a Web API

After you have a record type constant, we will create a new Web API named AT_QueryEmployees:

1. In the application view, click NEW > Web API.
2. Choose the QUERY RECORD TYPE template.

3. In the Create Web API dialog, configure the following properties:

   Property	Description
   Record Type Constant	Select the record type constant you just created.
   Name	Enter: AT_QueryEmployees
   Endpoint	Enter: query-employees

4. Click CREATE.

You should now see a screen that looks something like the following:

The left-hand pane contains the expression generated by the template that you just selected. Take a moment to read over that expression to see what it's doing.

Test It Out

Before you save your changes, it's always a good idea to test them so that you can see if the behavior you want is what you actually have.

1. Click the Test Request button.

The area below the Test Request button should now show the result of the expression. As you can see, it is a JSON-encoded list of values from the Employees record. This is a good start, but let's see if we can make it do a bit more.

Filter by Department

One thing that you might commonly want to do is to inspect the incoming HTTP request and use values from it in your expression. Let's walk through how to look at the request's query string and use one of its parameters to filter down the list of records that we return.

1. Click + New Query Parameter.
   • For Name, enter: department
   • For Value, enter: Sales
2. Click Test Request.

The Test Request button evaluates the expression with the new HTTP request shown in the Test Inputs section (you can see in the URL field in the image above that there's now a new query parameter) but the result of the expression didn't change. This is because our expression doesn't yet use the department parameter. Let's add that in now.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
a!localVariables(
  /*
  * Run the "queryrecord()" function on "cons!AT_EMPLOYEE_RECORD" to retrieve data for the
  * first 50 records and store this data in a local variable named "local!records".
  */
  local!records: queryrecord(
    cons!AT_EMPLOYEE_RECORD,
    a!query(
!      filter: a!queryFilter(
!        field: "department",
!        operator: "=",
!        value: http!request.queryParameters.department
!      ),
      pagingInfo: a!pagingInfo(
        startIndex: 1,
        batchSize: 50
      )
    )
  ).data,

  /*
  * Construct an HTTP response that contains the information that we just stored
  * in "local!records".
  */
  a!httpResponse(
    /*
    * Set an HTTP header that tells the client that the body of the response
    * will be JSON-encoded.
    */
    headers: {
      a!httpHeader(name: "content-type", value: "application/json")
    },
    /*
    * JSON-encode the value of "local!records" and place it in the response body.
    */
    body: a!toJson(value: local!records)
  )
)

Now when you click the Test Request button again, you will see that now the only Employee records that are included in the result are the ones that are in the Sales department. Take a minute and try putting some different values in the department parameter in the test interface.

However, we're not quite done yet. You might have noticed while you were experimenting with different values for the department parameter that if it is blank (or if there is no department parameter at all) that our expression breaks. This is because we can't pass a blank value into the value parameter of a!queryFilter(). To fix this we'll need to only specify a filter for queryrecord() if http!request.queryParameters.department is not null.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
a!localVariables(
  /*
  * Run the "queryrecord()" function on "cons!AT_EMPLOYEE_RECORD" to retrieve data for the
  * first 50 records and store this data in a local variable named "local!records".
  */
  local!records: queryrecord(
    cons!AT_EMPLOYEE_RECORD,
    a!query(
!      filter: if(
!        isnull(http!request.queryParameters.department),
!        null,
!       a!queryFilter(
!          field: "department",
!         operator: "=",
!          value: http!request.queryParameters.department
!        )
!      ),
      pagingInfo: a!pagingInfo(
        startIndex: 1,
        batchSize: 50
      )
    )
  ).data,

  /*
  * Construct an HTTP response that contains the information that we just stored
  * in "local!records".
  */
  a!httpResponse(
    /*
    * Set an HTTP header that tells the client that the body of the response
    * will be JSON-encoded.
    */
    headers: {
      a!httpHeader(name: "content-type", value: "application/json")
    },
    /*
    * JSON-encode the value of "local!records" and place it in the response body.
    */
    body: a!toJson(value: local!records)
  )
)

Now if the department query parameter is blank, the Web API will return an unfiltered list. If it is not blank, the Web API will filter by the department field.