Web API Tutorial - Level II

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 before beginning.

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. Navigate to the application contents view of the Appian Tutorial application.
  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_ENTITY
    • For Type, select Data Store Entity
    • For Data Store select AT Employees
    • For Entity, select Employees
    • For Save In, use the picker to select the Examples folder
  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. 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 Add Employee
    • Change the HTTP Method to POST
    • For Endpoint, type add-employee
  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 Write to Data Store under the Create section.
  2. In the resulting dialog, select the AT_EMPLOYEE_ENTITY constant that we created above.
  3. Click Generate.

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. Edit the Body field in the Test Inputs section to read:
  2. ```json { "firstName": "Frank", "lastName": "Sullivan", "department": "Sales", "title": "Sales Associate", "phoneNumber": "555-962-8452", "startDate": "3/27/2011" } ```
  3. Click the Test Request button again.

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:
  2. ```SAIL with( 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" } ) ) ) ) ) ```
  3. 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.

FEEDBACK