This articles covers the basic steps involved with creating web APIs along with examples of a GET & POST request to 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:
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.
Web APIs that use the POST
, PUT
, DELETE
, or PATCH
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"
}
)
)
)
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. HTTP headers which contain sensitive information are not included in the dictionary. This includes headers with keys like Authorization or Appian-API-Key . |
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. |
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.
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.