This tutorial walks you through creating a Web API that will write data into a Data Store. It builds on the progress you made in the Web API Tutorial, so you should be sure to complete that tutorial before beginning this one.

Setup

Complete the Web API Tutorial.

Create a data store entity constant

In order write to a data store with a web API, we are going to use the a!writeToDataStoreEntity() expression function. This function requires a data store entity constant for one of its parameters. So before building our web API, we need a data store entity constant to select.

1. Go to the Build view of the Appian Tutorial application.
2. Click NEW > Constant.

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

   Property	Description
   Create from Scratch	Leave selected.
   Name	Enter: AT_EMPLOYEE_ENTITY
   Type	Select Data Store Entity.
   Data Store	Select AT Employees.
   Entity	Select AT Employees.
   Save In	Keep the default folder, AT Rules & Constants.

4. Click CREATE.

Create a web API

Now that we have a Data Store Entity constant, create a new web API named AT_AddEmployee:

1. In the Build view, click NEW > Web API.
2. Choose the WRITE TO DATA STORE template.

3. Configure the following properties:

   Property	Description
   Data Store Entity Constant	Select the data store entity constant you just created.
   Name	Enter: Add Employee
   Endpoint	Enter: add-employee

4. Click CREATE.
5. Keep the default security settings.

Your screen should look 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

1. Click the Test Request button.
2. You should see that the Write to Data Store Entity smart service executed and wrote an empty type!Employee to the Data Store.
   

   

3. Look at the Employee table in your database. You should see a new row where only the id column has a non-null value because we didn't provide any employee data when testing the Web API. Next, we'll add data and test it again.

Providing test data

Our web API works by looking at the body of the incoming HTTP request, converting the JSON it finds there into an type!Employee CDT and writing that CDT to the database. When we tested the web API above, the content of the test HTTP request's body was {}, which in JSON represents an empty object. But that's not really what we want to test.

1. From the Test Inputs section, copy and paste the following expression in the Body field:

   1
   2
   3
   4
   5
   6
   7
   8
   {
     "firstName": "Frank",
     "lastName": "Sullivan",
     "department": "Sales",
     "title": "Sales Associate",
     "phoneNumber": "555-962-8452",
     "startDate": "3/27/2011"
   }
   

2. Click Test Request.

This time you should see that the Write to Data Store Entity smart service executed with data that matches what you put into the Body field. If you check the database again, you'll see a new row in the Employee table with the provided data.

Preventing updates

At this point, we have a web API that takes data from the body of an HTTP request and passes it into the Write to Data Store Entity smart service. The Write to Data Store Entity smart service then either creates a new row in the database or updates an existing row, depending on the data provided. If you want to ensure that the API never updates existing data, you need to make some changes.

Let's add a check that prevents the web API from updating existing employees. The way the Write to Data Store smart service knows if it should update an existing row in the database or create a new one is whether the value in the valueToStore parameter contains a value for the primary key. In this case, that's the id field. So if we want to prevent updates, we need to check to see whether the id is null and only call the Write to Data Store Entity smart service if it is.

1. Change the expression to be the following:

   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
   43
   44
   45
   a!localVariables(
     local!value: cast(
       'type!{urn:com:appian:types:Employee}Employee',
       a!fromJson(http!request.body)
     ),
     `if(`
       `not(isnull(index(local!value, "id", null))),`
       `a!httpResponse(`
         `statusCode: 400,`
         `headers: {`
           `a!httpHeader(name: "Content-Type", value: "application/json")`
         `},`
         `body: a!toJson(`
           `{`
             `error: "The provided Employee data included an id, which is not allowed.  " & `
             `"You can only create new employees, not modify ones that already exist."`
           `}`
         `)`
       `),`
       a!writeToDataStoreEntity(
         dataStoreEntity: cons!AT_EMPLOYEE_ENTITY,
         valueToStore: local!value,
         onSuccess: a!httpResponse(
           statusCode: 200,
           headers: {
             a!httpHeader(name: "Content-Type", value: "application/json")
           },
           body: a!toJson(
             fv!storedValues
           )
         ),
         onError: a!httpResponse(
           statusCode: 500,
           headers: {
             a!httpHeader(name: "Content-Type", value: "application/json")
           },
           body: a!toJson(
             {
               error: "There was an error writing to the data store"
             }
           )
         )
       )
     )
   `)`
   

2. Add an id value to the test body and hit the Test Request button again.

This time, instead of executing the Write to Data Store Entity smart service the web API returned an HTTP response with a status code of 400 (meaning Bad Request) and a body that explains to the caller what they did wrong.