Service Endpoints

A Service Endpoint defines an interface for interacting with a service. Endpoints are designed to receive a request and return a response.

Service Endpoints can be used when a third-party system wants to integrate towards Appfarm. Please read more here.

Usage

To add an endpoint to a service:

• Open the service.

• Click the + icon in the Service Endpoints panel.

• Enter a name for the endpoint.

To see and test and all endpoints in your solution open the API explorer.

To call an endpoint from an external service, including tools like Postman, construct an endpoint URL as follows: https://SOLUTION-HOSTNAME/api/services/SERVICE-ALIAS-SLUG/READABLE-ID.

When you create an endpoint, not all properties will be relevant. The properties you need will be dependent on the use case you are designing the endpoint for.

If you are receiving data from an external service (POST), the properties under Request data will be most relevant, as these are used to parse and map the data being sent.

If you are receiving queries from an external service (GET), both Request data and Response data will be required.

If you are running the endpoint to process or send data on a schedule (GET), Process action might be the only property you need.

Endpoints can be set to be executed asynchronously. For example, if the action performed is time-consuming (such as syncing large amounts of data), the service should return an OK response immediately, along with a Job ID.

General properties

Property	Description
Name	A descriptive name for the endpoint. This is shown in the API explorer and logs.
Description	A longer description of the endpoint. It may be useful to describe what this endpoint expects in a request and returns in a response. This is shown in the API explorer.
Enable Log	Create a log entry when this endpoint is called.
Methods	The HTTP request methods that the endpoint will support. The available options are: GET POST PUT PATCH DELETE Read more about HTTP request methods on MDN Web Docs. Note: Only Endpoints with the GET method enabled is possible to execute from a Schedule in Appfarm.
Readable ID	A string that will be used when generating the endpoint URL. It is common to use a verb that represents the purpose of the endpoint. For example, in the following endpoint URL the readable ID is list: https://thirty50.appfarm.app/api/services/events/list
URL Parameters	Add path parameters, which are required parts of the endpoint URL. Path parameters are often used to specify a specific object and can be bound to a data source. A path parameter can also be a static string. Variable path parameters are documented in the API explorer with a leading colon, for example: https://thirty50.appfarm.app/api/services/events/details/:param1

Request data

These properties enable you to parse and map data sent as part of a request to the Endpoint.

Property	Description
Query Parameters	Map values from query parameters into single-cardinality data sources.
Header Values	Map values from request headers into single-cardinality data sources.
Body Parser	Parse body data into JSON. If the request contains body data that is not in JSON, you can use the function editor to create a JSON object containing the data so that you can map it into data sources. Not available for GET.
Body Data	Map request body data in JSON format into data sources. Not available for GET. Note: The maximum size of the incoming body (in MB) for POST requests is 1 MB. You may override the Max Payload Size in the Service Security section of Environments Config.

Response data

These properties enable you to configure the headers and data sent in the response.

Property	Description
Response Headers	Add custom headers or override default headers in the response. Response headers are evaluated after populating data sources and running the action specified in Process Action.
Data Sources	Data sources to return after running the action specified in Process Action. All data in the selected data sources will be included in the response. If the endpoint is called by a schedule you should not select any data sources as the response is ignored and performance will be slightly degraded.
Custom Response Body	Construct a custom response body using the function editor. This can be used instead of returning Data Sources.

Data processing

Property	Description
Process Action	An action to execute when the endpoint is called. Request data is populated before the action is run.
No Concurrency	Disable concurrency for this endpoint. If this is selected, the service will fail if it is called while already running. Note that it will not queue the request and run it after the last one automatically.
Run Async	Enable asynchronous processing for this endpoint. If this is selected, the endpoint will return a response immediately instead of waiting for the Process Action to complete. The response will contain a job ID. This option should be used for actions that are expected to run for more than 2 minutes. If logging is enabled, it will still write the result to the log. Make sure to set Job Timeout to a reasonable value.
Job Timeout	If Run Async is selected, you can specify a timeout in seconds, up to a maximum of 4 hours. The default is 300 seconds (5 minutes). This timeout acts as a safeguard in case the job suffers from a catastrophic failure. For example, if the runner quits unexpectedly and is unable to mark the job as complete nor failed. It will also kill the job and mark it as failed if it runs longer than this timeout. This value should be set well above the expected runtime, but not exceedingly high. This is especially important when No Concurrency is selected. If a deploy occurs when a job is running (this includes automatic deployments in Development), the job will be interrupted, but the timeout will not be reset. If No Concurrency is selected, the job cannot be started again until the timer expires.

Advanced

Property	Description
Cache Response Data	Enable caching for this endpoint. If this endpoint returns data which is static or not time sensitive you can cache the response data to increase performance.
Cache Timeout	If Cache Response Data is selected, you can specify a timeout in seconds, up to a maximum of 24 hours. The default is 3,600 seconds (1 hour).
Enable Rate Limiter	You may set restrictions on how many parallel connections ("Rate Limit Points") a single IP may have towards this endpoint, within a given time window ("Rate Limit Window"). Note that you may also control this in the Service Settings.