Web APIs provide a way to expose Appian data and services to outside systems.
Web APIs are created much like expression rules, however there are two main differences between them. First Web APIs also include an end point that can be called by other systems. Second, a designer doesn't configure rule inputs for Web APIs, instead passing values to the Web API via query parameters, headers, a body, or any combination of the three.
Web APIs use the same authentication mechanism that the rest of Appian uses. This means that in the standard out-of-the-box configuration there are two different ways to authenticate with Appian in order to call a Web API:
While both authentication methods are supported, if you wish to invoke an Appian Web API from another system, you must use HTTP basic authentication.
HTTP basic authentication for Appian Web APIs requires preemptive authentication. Unauthorized requests will not prompt clients for credentials with a 401 status code.
Standard forms-based login in authentication is reserved for user-initiated Web-API calls. If you are invoking an Appian Web API from a user's browser (for instance to populate a task list for use with an embedded interface), we recommend setting up SSO between Appian and the site that will initiate the call to the Web API. Web APIs honor existing session cookies.
You can add to or modify these options by configuring the authentication for your site. As a reminder, you should never store passwords for connecting to Appian in plaintext.
HTTP requests made by one web site to another are said to be "cross-origin" because the origin (the url) of the first web site is different than the origin of the other site. Web browsers block requests of this nature by default for security reasons. However, web sites that wish to opt into allowing other sites to access their resources can use a standard called "Cross-Origin Resource Sharing", or CORS, to mark resources as being shareable with other sites. To configure this in Appian, you must add any sites you wish to expose data or services to in this manner to the allowed origins list in the Appian Administration Console.
For POST, PUT, and DELETE Web APIs, adding a web site to the allowed origins list will also exempt that site from Appian's built-in cross-site request forgery (CSRF) protection. You should not add sites that you don't trust to the allowed origins list.
When creating or editing a Web API, designers can select from one of the following HTTP methods: GET, POST, PUT, and DELETE. Additionally, the HTTP methods OPTIONS and HEAD are automatically handled by the system based on the Web APIs that exist in the system for a given Endpoint.
HEAD requests will execute the Web API for the GET method for the Endpoint and return the result, minus the response body.
OPTIONS requests will return a list of methods for which Web APIs exist for a given Endpoint.
For example, assuming that you have two Web APIs with the Endpoint field set to customer, one for GET and one for POST, and you make an OPTIONS request to https://www.example.com/suite/webapi/customer, the response will looks something like the following.
1
2
3
4
5
6
7
8
9
10
11
12
HTTP/1.1 200 OK
Date: Tue, 19 Apr 2016 15:27:22 GMT
Server: Apache
Pragma: No-cache
Cache-Control: no-cache
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-Frame-Options: SAMEORIGIN
Allow: GET, POST, OPTIONS
Content-Length: 0
Keep-Alive: timeout=20, max=100
Connection: Keep-Alive
Content-Type: text/plain
Note that the Allow header contains entries for both GET and POST.
Only Web APIs for the POST, PUT, and DELETE methods may execute smart services. Web APIs for the GET method will not execute any smart services included in their expression. Attempting to do so will result in the following error message: Smart Services cannot be executed in Web APIs that have a method of "GET."
There are several factors that affect what HTTP status code a Web API returns.
| Status Code | Condition |
|---|---|
| 404 | There is no Web API with the specified endpoint and HTTP method |
| 404 | The user is not in the viewer role or higher for the Web API |
| 500 | There was an error evaluating the Web API's expression |
| 500 | The result of the expression evaluation was not an HTTP Response object |
Additionally, designers may specify in their expression a status code that the Web API should return. This allows them to do things like return a 404 code if data about a record that does not exist is requested.
Each Web API has a rolemap that specifies its viewers, auditors, editors, and administrators.
The rights for each role are described in the following table.
| Actions / Roles | Administrator | Editor | Auditor | Viewer |
|---|---|---|---|---|
| Execute | Yes | Yes | Yes | Yes |
| View the configuration | Yes | Yes | Yes | Yes |
| View the security | Yes | Yes | Yes | No |
| Update the configuration | Yes | Yes | No | No |
| Update the security | Yes | No | No | No |
| Delete | Yes | No | No | No |
To access the Web API object's definition and rolemap, users must also be in the designer role.
The Administrator user may view, edit, and delete Web APIs but may not execute them. This includes testing them inside the Web API Designer.
All versions of an object are saved and designers can view the definitions of old versions; however, when invoked, it is always the latest version that executes.
Versions of a single object can be accessed by users with Viewer permissions, by doing one of the following:
This option opens the Versions dialog with a list of versions:
If you wish to revert to an older version, open that version by clicking on it and save it. This will create a new version of the object with the definition that is currently loaded in the designer. Modifying a previous version and saving it as the latest version does not affect the old version. To avoid confusion, you should close the tab from which you opened the Versions dialog, since it now contains an old version.
Versions can be deleted by users with Editor permissions and if there are multiple versions. A single version can be deleted by clicking the corresponding red X in the rightmost column of the versions grid.
Bulk deletion can be done by selecting filter criteria that returns multiple versions, which causes a message to appear that prompts you to delete the filtered versions. If the latest version is included in the filtered results, it will not be affected by the bulk deletion. This allows for easier and faster cleanup of object versions, in order to maintain useful versions and prevent version buildup that may affect engine memory.
Web APIs do not support deleting versions.
If there is an error executing the expression associated with a Web API, the error message appears in logs/design_errors.csv rather than in the standard application server error log.
See also: Web API Performance Logs and Web API Metrics Logs
The performance view shows you detailed performance information for your web API. This allows you to identify and address performance bottlenecks and to understand the impact of particular rules and functions.
The performance view can be accessed using the Performance View option in the gear menu in the header. See the Performance View page for more information on how to use the performance view.
