Creating Web APIs

Overview

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

  • To learn about web APIs and their configuration options, see Web APIs.
  • For a real-world example of how to build and test web APIs in Appian, see the Web API Tutorial.
  • To learn about web API authentication, see Web API Authentication.

Creating a Web API

When you create a web API, 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 can also create a web API from scratch.

To create a web API:

  1. Open the Appian Designer.
  2. Create a new application or open an existing one.
  3. Click New, and then click Web API.
  4. If desired, select a template. Otherwise, select Create from scratch.
    • Note: Selecting a template will automatically select some fields, such as the HTTP method and whether or not to convert the request body to an Appian document. It will also populate the Create Web API dialog box with any extra fields that are required for the template.
  5. Enter a name for the web API. This name is displayed only to Appian developers.
  6. If you are creating from scratch, select an HTTP method.
  7. 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.
    • Note: The combination of the HTTP method and endpoint must be unique across all web APIs in the system.
  8. If using a template, make sure any remaining fields required for the template are filled out.
  9. Click Create.

If you used a template, you'll notice that the 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 Variant (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 forward slashes: /. The first item in the list will be the section of the URL that immediately follows the endpoint.

Because this list is wrapped in a Variant, count(http!request.pathSegments) will always return 1. To get around this, designers can cast the field to a List of Text: count(cast(typeof({""}),http!request.pathSegments)).

Indexing into pathSegments on the other hand, still works as it would for any list: index(http!request.pathSegments, 1, null).
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. Once set, the default values will be saved with the interface.

FEEDBACK