Web APIs

Introduction

This article provides detailed design information about the Web API design object and its configuration options.

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.

images: web_api_desinger.png

Invoking a Web API

Authentication

To learn about web API authentication, see Web API Authentication.

Cross-Origin Requests

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.

HTTP Headers

HTTP headers allow the designer to pass additional information with the response. Appian will automatically send several response headers, including Content-Length, Date, Server, and more. The designer can pass any additional headers they deem necessary.

When a document is returned in the body, two headers are automatically added: Content-Type, and Content-Disposition. The generated Content-Type header returns the type of the document. For example, if a GIF file is returned, the value of Content-Type is image/gif. The generated Content-Disposition header holds a value of inline, indicating that the document will be viewed inline in the browser, rather than being downloaded as an attachment for local viewing. This Content-Disposition header also contains the filename of the returned document. The designer can override these headers by manually setting them in the headers parameter of a!httpResponse().

HTTP Methods

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."

HTTP Status Codes

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.

Recommendations

While editing your web APIs you may encounter recommendations. Appian recommendations are best practice design patterns that should be implemented in your objects. Recommendations for web APIs are calculated while editing the web API or when a precedent of the web API is updated.

When recommendations are triggered for a web API, a lightbulb lightbulb_icon icon (A) will appear in the Appian header next to the Save Changes button and when applicable, a lightbulb icon will also appear next to the relevant field or line. Click on the icon in the header to learn more about the recommendations (B) and how they can be addressed. If a recommendation is not applicable to your use case, you can Dismiss (C) that individual recommendation for that web API. Learn more about recommendation dismissal.

Web API recommendations are also visible outside of web APIs on the Health Dashboard.

See expression recommendations for the full list of possible web API recommendations.

A user must have at least Viewer permissions to a web API in order to execute it.

The security role map of a web API controls which users can see or modify it and its properties. By default, only the web API creator and system administrators have access to the web API. See Editing Object Security to modify an web API's security.

The following table outlines the actions that can be completed for each permission level in a web API's security role map:

Actions Administrator Editor Viewer
Execute the web API* Yes Yes Yes
View the web API definition Yes Yes Yes
View the security Yes Yes Yes
Update the web API definition Yes Yes No
Update the security Yes No No
Delete the web API Yes No No

*The Administrator user may view, edit, and delete Web APIs but may not execute them. This includes testing them inside the Web API Designer.

Versions

Each time you modify and save a Web API, a new version is created. All objects that use the Web API will use the latest version. All versions are accessible to designers who can view the Web API, and a Web API can be reverted back to a previous version at any time.

For information on how to manage object versions, see Managing Object Versions.

Web APIs do not support deleting versions.

Uploading and Downloading Binary Document using Web APIs

Web APIs can be used to upload a document to Appian in a binary request body. The size of this document is limited to 75 MB.

They can also be used to download a document from Appian in a binary response body.

Logging

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

Share Web API Documentation with OpenAPI

The OpenAPI Specification defines a standard which allows both humans and computers to discover and understand the web APIs available to them. These files can even be consumed in order to automatically configure the client being used to call Appian.

images: web_api_desinger.png

To generate an OpenAPI definition for the web APIs in an application, navigate to the Applications List in the Appian Designer and select that application. Then, click the Export button and you will click the option for OpenAPI Definition. This will only be enabled when you have exactly one application selected, and it contains at least one web API.

images: web_api_desinger.png

This will export a JSON file that uses OpenAPI version 3.0.1. In addition to the file name and description you specified upon export, the OpenAPI definition includes the environment's base URL and the available authentication options.

For each endpoint, it specifies the method, path, and description. You can also include HTTP headers, query parameters, path parameters, and an example request body by setting default test values in the test pane. This is done by clicking the Set as default test values link and saving your web API.

images: web_api_desinger.png

To specify parameters for the query parameters and headers, simply add a value to the corresponding grid. To specify a path parameter, include the variable name in curly brackets, as shown in the example above.

The OpenAPI definition Appian generates does not include details about the response.

Open in Github

On This Page

FEEDBACK