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.

Create a Record Type Constant

/* The new a!queryRecordType doesn't require a constant, but the Web API wizard does.*/ 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. Choose the QUERY RECORD TYPE template.
  4. In the Create Web API dialog, complete the following fields:
    • For Record Type Constant, select the record type constant you just created.
    • For Name, type AT_QueryEmployees
    • For Endpoint, type query-employees
  5. Click Create.

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

Web API After Creation

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
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 and if it is not blank it will filter by the department field.

Open in Github Built: Thu, Feb 23, 2023 (02:59:22 PM)

On This Page

FEEDBACK