Service Endpoints
Last updated
Was this helpful?
Last updated
Was this helpful?
A Service Endpoint defines an interface for interacting with a . Endpoints are designed to receive a request and return a response.
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 .
To call an endpoint from an external service, including tools like , 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 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 and 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 . 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.
Name
Description
Enable Log
Methods
The HTTP request methods that the endpoint will support. The available options are:
GET
POST
PUT
PATCH
DELETE
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.
These properties enable you to parse and map data sent as part of a request to the Endpoint.
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
These properties enable you to configure the headers and data sent in the response.
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.
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.
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
A descriptive name for the endpoint. This is shown in the and .
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 .
Create a when this endpoint is called.
Read more about . Note: Only Endpoints with the GET method enabled is possible to execute from a in Appfarm.
Variable path parameters are documented in the with a leading colon, for example: https://thirty50.appfarm.app/api/services/events/details/:param1
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 section of Environments Config.
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 .