What are Web APIs?
API is a set of subroutine definitions, communication protocols, and tools for building software. Web API, as the name suggests, is an API over the web which can be accessed using HTTP protocol.
A server-side web API is a programmatic interface consisting of publicly exposed endpoints to a defined request–response message system. REST and SOAP are two types of most popular web APIs. REST web APIs are based on HTTP methods to access resources via URL-encoded parameters and the use of JSON or XML to transmit data. SOAP protocols are standardized by the W3C and mandate the use of XML as the payload format, typically over HTTP.
What can Web APIs do in Appian?
In Appian, Web APIs provide the possibility of exposing Appian data and services to external systems through REST web services. Each Web API is an association between a URL/HTTP method combination and an expression. When a client makes an HTTP request of a certain method (GET, POST, PUT, DELETE) to the given URL (also called “endpoint”), the associated expression is executed and the result is returned to the client. Therefore, any data or service that is available for an expression can be exposed to external systems, including:
- Details of tasks and records;
- Appian document;
- Write to a data store entity smart service;
- Start a new instance of a process model smart service; etc.
Benefit of Web APIs
The benefits of using Web API in Appian are evident:
- REST Web APIs are accessible by a variety of HTTP clients, including programs, apps and web browsers installed on various operating systems and devices;
- They are easy to create and maintain. Expressions executed by Web APIs are defined in the same way as other expression rules in Appian. The development environment is low-code and equipped with powerful declarative tools;
- They are standardised and reusable. One web API can be used by objects in the same or different Appian environment and external systems at the same time;
- High data security. Appian user authentications are required for the use of Web APIs. The correct authentication key or username/password pair needs to be provided while sending the HTTP request. In addition, HTTP clients - logged in as the authenticated user in Appian, can only get access to the data and services with minimum viewer/initiator level of permission.
Create a Web API in Appian
- Step 1: In an application in Appian Designer, select “New > Web API” to open the “Create Web API” dialog;
- Step 2: Fill in the name, HTTP method, description and endpoint for the Web API and click “CREATE” to create the new Web API object. It also opens the Web API designer;
- Step 3: Select a template or start from scratch by clicking “CLOSE”;
- Step 4: Plan for the path, headers and query parameters of the expected incoming HTTP requests;
- Step 5: Design the user authentication method. There are mainly two methods to be considered. The first one is that all HTTP requests adopt the same user authentication. The Appian contents exposed via this type of web API are the same to all external systems and users. The second type of structure is that each HTTP request uses different Appian user authentication. Therefore, the exposed contents vary based on the security assigned to each user. The methods also determine how loggedInUser() function can be used in the executed expressions;
- Step 6: Develop the expressions to be executed when a valid request is received. Consider the impact of different paths, headers, query parameters and user authentication methods;
- Step 7: Define the response using a!httpResponse() function. Configure the headers and body of the response. The response body is suggested to be in JSON or XML format. However, plain text or HTML with JavaScript are also worth considering.
- Step 8: Review the security of the Web API object together with relevant expression rules, process models, document folders and data stores;
Send an HTTP Request to a Web API from external systems
Since the Web APIs are designed as REST web services, any systems can exchange information with Appian by sending HTTP requests to the correct endpoint with valid method and headers containing Appian user authentication.
If the external system is also Appian-based, connected systems and integrations need to be used for sending HTTP requests.
Most of the time, the external systems can be different platforms, or simply programs and apps developed in programming languages such as C#, Java, etc. The following steps should be followed to develop functions for sending HTTP requests to Appian.
- Step 1: Provide the request URL and method. The request URL should be a combination of the endpoint, path and query parameters as defined in the Web API.
- Step 2: Add headers to the request. Appian user authentication needs to be added in a header with the name “Authorization”. The value can be generated based on HTTP basic authentication (string: “Basic ” + base64-encoded credentials).
- Step 3: Define the content of the requests. Note that the content is supposed to be a serialized string in specific formats. JSON is the most recommended format by Appian. A “Content-Type” header can also be added to the request at this stage.
- Step 4: Develop the reception and deserialization of HTTP responses, and design how the Appian contents in the response are processed and displayed to the end users.
List of abbreviations
API: Application Programming Interface
HTTP: Hypertext Transfer Protocol
JSON: JavaScript Object Notation
REST: Representational State Transfer
SOAP: Simple Object Access Protocol
URL: Uniform Resource Locator
XML: Extensible Markup Language