Mapsly allows you to expose custom API endpoints in Mapsly so that your external IT system and call it programmatically to execute custom business logic in Mapsly and receive the response, for example, to retrieve the list of territories to which a location on the map belongs.
To create a custom API endpoint, go to the API Endpoints page:
Mapsly will check if an API key has already been generated for the Mapsly System source, which will be required to call this endpoint. If the API key has not yet been generated, Mapsly will generate it for you:
The following parameters will become available for configuration:
Call mode:
Choose Sync if you want the endpoint to execute and return the response synchronously.
Note. The max time Mapsly will keep the connection open will be limited by the max session execution time, which is 10 minutes by default.
Choose Async if you want Mapsly to queue the execution and immediately return HTTP response code 200 with the body
{"result":"ok"}, and once the execution has been completed, call your callback URL to pass the result. In this mode, enter your callback URL:
Authentication: choose between the 2 auth available authentication options:
API key: when called, this endpoint will verify the API key before executing the Button's condition/actions blocks. Choose this option if you plan to call this endpoint from your server and not from a public web resource. In this case, Mapsly will append the Mapsly System source's API key to the endpoint's URL.
IMPORTANT NOTE. Do NOT use API key-based authentication if this Mapsly API endpoint will be called from a public-facing web resource. Doing so would compromise your API key, enabling anyone to access and overwrite your Maps y data.
URL signature: when called, this endpoint will only verify the URL signature present in the URL as a parameter. Use this option if the endpoint will be called from a public web resource to ensure that the URL parameters have not been altered.
When you choose this option, Mapsly will automatically append your endpoint's URL with a default URL signature generated for your endpoint's URL without any other URL parameters. If you'd like to pass some URL parameters to this endpoint, you will need to re-sign your URL using SignUrl) function for every unique set of URL parameters.Mapsly Auth: When 'Mapsly Auth' is selected, this endpoint will only be executed for users currently logged in inside Mapsly. This authentication is used for launching custom internal apps.
Accessing the Request
You may access the request data in the Button's condition/actions using the request object of the execution context, which contains 4 keys: url, method, parameters, and body (when present). Parameters contain an array of url_param:value pairs.
Example of the request object using GET:
Example of the request object using POST:
Returning Response
In the Sync mode, the endpoint returns data in the following format upon completion of the execution session:
{"code": your_code, "data": your_response}
In the Async mode, upon completion of the execution session, Mapsly will call the callback URL and pass {"code": your_code, "data": your_response} in the request body.
Note. Mapsly will keep the connection open until the execution session terminates.
Response code
To return a specific HTTP code in the Sync mode, set the code variable in the execution context. When this variable is missing, the endpoint will return code 200.
Response body
To return the response body, set the response variable in the execution context.