Creating Web APIs

Designing a Web API

This articles covers the basic steps involved with creating an APIs along with examples of a GET & POST request to a Web API.

Creating a Web API

  1. Open the Appian Designer.
  2. Create a new application or open an existing one.
  3. Select New > Web API. This opens the Create Web API form.
  4. Enter a name for the Web API. This name is displayed only to Appian designers.
  5. Select an HTTP method.
  6. Enter an endpoint for the Web API. This is used as part of the Web API's URL to identify it and will be seen by end users and in log files for network devices and servers.
    • The combination of the HTTP method and endpoint must be unique across all Web APIs in the system.
  7. Click Create & Edit. This opens the Web API designer.

Templates

When you first open the Web API Designer and the Web API doesn't already have an expression defined, the first thing that you will see is a dialog with a selection of templates that you can pick from. These templates are intended to give you a starting point from which you can quickly build out your Web API.

Selecting one of the templates will populate your Web API with an example expression and test inputs and convert it to use the proper HTTP method for that expression.

You'll notice that each template expression returns an HTTP Response object, built with a!httpResponse(). All Web APIs must return an HTTP Response.

Executing a Smart Service

Web APIs that use the POST, PUT, or DELETE HTTP methods are able to execute a smart service.

Every smart service that can run inside a Web API has an onSuccess and an onFailure parameter that expects an HTTP response defined using a!httpResponse(). When the smart service executes successfully, the HTTP response defined in the onSuccess parameter is returned. When the smart service encounters an error and is unable to execute, the HTTP response defined in the onError parameter is returned.

The example below uses the Write to Data Store Entity smart service. When the write is successful the Web API results in an HTTP response with a 200 status code and a body containing the JSON-encoded data that was written to the data store. When the write is unsuccessful, the Web API results in an HTTP response with a status code of 500 and a body containing a JSON-encoded error message.

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
a!writeToDataStoreEntity(
  dataStoreEntity: cons!EMPLOYEE_ENTITY,
  valueToStore: type!Employee(
    firstName: http!request.queryParameters.firstName,
    lastName: http!request.queryParameters.laseName,
    department: http!request.queryParameters.department,
    title: http!request.queryParameters.title
  ),
  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"
      }
    )
  )
)

Accessing The HTTP Request

Data from the incoming HTTP request is exposed to the expression in the variable http!request. This variable is a dictionary that contains the following fields:

Field Type Description
url Text The URL of the incoming request, including protocol, hostname, port, path, and query parameters
pathSegments List of Text A list of text where each item in the list corresponds to a segment of the URL from the incoming request separated by /s. The first item in the list will be the section of the URL that immediately follows the endpoint.
queryParameters Dictionary A dictionary where the keys are the names of the query parameters from the request and the values are the values of those parameters
headers Dictionary A dictionary where the keys are the names of the headers from the request and the values are the values of those headers
body Text The body of the incoming request
formData Dictionary An alternate representation of the request body that is a dictionary where the keys are the names of the fields from the body of the request and the values are the values of those fields. This is only available when the the incoming request contains a Content-Type header with a value of application/x-www-form-urlencoded and the contents of the request body can be parsed as that content type.

Examples

GET Requests

If a user makes a GET request to https://www.example.com/suite/webapi/customer?customerId=5 the value of http!request will be the following:

Field Value
url https://www.example.com/suite/webapi/customer?customerId=5
pathSegments {}
queryParameters {customerId: "5"}
headers {}
body ""

In the above example, you can extract the value of the customer ID from the request using the expression http!request.queryParameters.customerId.

Expression Value
http!request.queryParameters.customerId "5"

However, if the user instead makes a GET request to https://www.example.com/suite/webapi/customer/5 with no headers the value of http!request will be the following:

Field Value
url https://www.example.com/suite/webapi/customer/5
pathSegments {"5"}
queryParameters {}
headers {}
body ""

In the above example, you can extract the value of the customer ID from the request using the expression http!request.pathSegments[1].

Expression Result Value
http!request.pathSegments[1] "5"

Note that in both examples above, the ID of the customer was of type Text, not Number. This is because all HTTP URLs, including path and query parameters, are fundamentally text and not numbers. All values in the http!request.queryParameters and http!request.headers dictionaries are of type Text.

POST Requests

For POST requests, the body of the request is exposed in two fields: body and formData.

If a user makes a POST request to https://www.example.com/suite/webapi/customer where the body of the request contains id=7&name=Acme+Corporation&firstPurchaseDate=2016-03-12 and there a content type header with a value of application/x-www-form-urlencoded, the value of http!request will be the following:

Field Value
url https://www.example.com/suite/webapi/customer/
pathSegments {}
queryParameters {}
headers {Content-Type: "application/x-www-form-urlencoded"}
body "id=7&name=Acme+Corporation&firstPurchaseDate=2016-03-12"
formData {id:"7", name:"Acme Corporation", firstPurchaseDate:"2016-03-12"}

If the same request did not contain a content type header or if it had a value other than application/x-www-form-urlencoded, the formData field of http!request would have been null.

When designing a Web API, you can save a default value for your test HTTP request using the Set as default test values link in the Web API designer. Once set, the default values will be saved with the interface.

FEEDBACK