Merge pull request #13 from flightaware/BCK-7183_update_README_clarifications

Update README Clarifications
Add endpoint to return endpoint for where triggered alerts are sent.

BCK-7183

Author: jacob-y-pan

.env-sample

@@ -1 +1,3 @@
-AEROAPI_KEY=key
+AEROAPI_KEY=key
+POST_PORT=8081
+WEB_SERVER_PORT=8080

README.md

@@ -32,8 +32,8 @@ and `docker-compose up` creates containers from those images and launches them.
 If you'd like to build the images yourself, you can instead run
 `docker-compose up --build`.
 
-*For alert creation, the commands will all be the same except add `-f 
-docker-compose-alerts.yml` to utilize the alerts docker compose file. For 
+*For alert creation, the commands will all be the same except add `-f
+docker-compose-alerts.yml` to utilize the alerts docker compose file. For
 example, instead of `docker-compose --profile python up`, you should have
 `docker-compose -f docker-compose-alerts.yml --profile python up`*.
 
@@ -45,3 +45,35 @@ log as requests are made to them.
 You can test out the FIDS/Alerts sample application by visiting http://localhost:8080 in
 your web browser (if not running Docker locally, use the Docker host's
 address).
+
+## Alerts Backend Note:
+
+Whenever an event is triggered for an  alert, AeroAPI will send a POST request to your 
+configured endpoint. In order to configure your endpoint, you need to publicly expose its
+address/port (specified using the POST_PORT environment variable, NOT the WEB_SERVER_PORT variable).
+Furthermore, as noted in the docker-compose-alerts.yml file, we encourage the service for
+accepting POSTed triggered alerts to be isolated, and thus will be sent to a different Docker
+container. This means that you will have to set the endpoint URL using /post, instead of /api/post.
+In order to get send your alerts to this webapp, you should configure this webapp 
+(http://localhost:8081/post for example) to receive alerts using a REST client like cURL,
+like the following command:
+```
+curl --location --request PUT 'https://aeroapi.flightaware.com/aeroapi/alerts/endpoint' \
+--header 'Content-Type: application/json; charset=UTF-8' \
+--header 'x-apikey: <YOUR API KEY>' \
+--data-raw '{
+  "url": "http://<YOUR IP>:8081/post"
+}'
+```
+(see the [documentation](https://flightaware.com/aeroapi/portal/documentation#put-/alerts/endpoint)
+for more information). NOTE: if you previously configured a different production endpoint to receive alerts,
+**you will change the same URL!** This means that ALL of your configured alerts
+will all be sent to the newly configured endpoint.
+
+You can see this newly configured URL by going to FlightAware's
+[push notification testing page](https://flightaware.com/commercial/aeroapi/send.rvt)
+or by going to the alert creation page on the webapp. On this push notification testing
+page, you can also do two things: test your configured endpoint on the backend to see if it
+receives a test triggered alert properly, and also see the success/failure of triggered alerts
+that were sent up to 24 hours in the past. If there was an error it will display the
+full error message.

alerts_backend/python/app.py

@@ -141,6 +141,20 @@ def delete_from_table(fa_alert_id: int) -> int:
     return 0
 
 
+@app.route("/endpoint")
+def get_endpoint_url() -> Response:
+    """
+    Return the configured endpoint URL for AeroAPI to send POST requests as a JSON payload.
+    """
+    api_resource = "/alerts/endpoint"
+    logger.info(f"Making AeroAPI request to GET {api_resource}")
+    result = AEROAPI.get(f"{AEROAPI_BASE_URL}{api_resource}")
+    url = "NO ENDPOINT CONFIGURED"
+    if result.json():
+        url = result.json()["url"]
+    return jsonify({"url": url})
+
+
 @app.route("/delete", methods=["POST"])
 def delete_alert() -> Response:
     """