Web API Tutorial

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.

For background on Web APIs and reference information on their behavior and how to build them in Appian, please see the Web APIs page.

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. Navigate to the application contents view of the Appian Tutorial application (if needed).
  2. Click New, and then click Constant.
  3. In the Create Constant dialog, complete the following fields:
    • Leave Create from Scratch selected
    • For Name, type AT_EMPLOYEE_RECORD
    • For Type, select Record Type
    • For Value select the Employee Directory
    • For Save In, use the picker to select the Examples folder
  4. Click Create.

Create a Web API

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

  1. Navigate to the application contents view of the Appian Tutorial application (if needed).
  2. Click New, and then click Web API.
  3. In the Create Web API dialog, complete the following fields:
    • For Name, type AT_QueryEmployees
    • Leave HTTP Method with the default of GET
    • For Endpoint, type query-employees
  4. Click Create & Edit.

Select a Template

When you first open the Web API designer, you'll see a palette of templates to chose from.

  1. Select Query Record Type under the Query section.
  2. In the resulting dialog, select the AT_EMPLOYEE_RECORD constant that we created above.
  3. Click Generate.

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, type department
    • For Value, type 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
with(
  /*
  * 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
with(
  /*
  * 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 and if it is not blank it will filter by the department field.

FEEDBACK