REST API
A short guide on deploying serverless REST APIs using Beam
Beam apps can be deployed using the rest_api decorator.
from beam import App, Volume, Output
app = App(
name="my-app",
volumes=[
Volume(name="files", path="./files"),
],
)
@app.rest_api()
def handler():
return
| Parameter | Required | Description |
|---|---|---|
runtime | No | The runtime environment to execute the tasks submitted via the API. It can be a dictionary containing runtime configurations or an instance of the Runtime class. Default is None. |
outputs | No | A list of outputs or output configurations for handling task results. Default is []. |
autoscaling | No | Autoscaling configuration. If not provided, autoscaling will not be applied. Default is None. |
loader | No | The function that runs exactly once when the app is first started from cold. Default is None. |
callback_url | No | A URL where task execution status updates will be sent. If provided, the system will make a single POST request to this URL with status updates for each task. Default is None. |
max_pending_tasks | No | The maximum number of tasks that can be pending in the queue before rejecting new submissions to the API. Default is 100. |
keep_warm_seconds | No | The duration in seconds to keep the container warm even if there are no pending tasks. Keeping the queue warm helps to reduce the latency when new tasks arrive via the API. Default is 100. |
Testing your function
Beam includes a live-reloading feature that allows you to run your code on the same environment you’ll be running in production.
By default, Beam will sync all the files in your working directory to the
remote container. This allows you to use the files you have locally while
developing. If you want to prevent some files from getting uploaded, you can
create a .beamignore.
In your shell, run beam serve app.py. This will:
- Spin up a container
- Run it on a remote server
- Print a cURL request to invoke the API
- Stream the logs to your shell
You should keep this terminal window open while developing.
(.venv) user@MacBook demo % beam serve app.py
i Using cached image.
✓ App initialized.
i Uploading files...
✓ Container scheduled, logs will appear below.
⠴ Starting container... 5s (Estimated: 3m20s)
================= Call the API =================
curl -X POST 'https://apps.beam.cloud/serve/3dpga/650b636542ef2e000aef54fa' \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Connection: keep-alive' \
-H 'Authorization: Basic [YOUR_AUTH_TOKEN]' \
-H 'Content-Type: application/json' \
-d '{}'
============= Logs Streamed Below ==============
INFO: | Starting app...
INFO: | Loading handler in 'app.py:predict'...
INFO: | Running loader in 'app.py:load_models'...
INFO: | Ready for tasks.
Now, head back to your IDE, and change a line of code. Hit save.
If you look closely at the shell running beam serve, you’ll notice the server reloading with your code changes.
You’ll use this workflow anytime you’re developing an app on Beam. Trust us — it makes the development process uniquely fast and painless.
Deploying the API
To deploy the app, enter your shell and run this command from the working directory:
beam deploy app.py:your_function
After running this command, you’ll see some logs in the console that show the progress of your deployment.
Calling the API
After deploying the API, you’ll be able to copy a cURL request to hit the API. In your app dashboard, click Call API.
Example Request
curl -X POST --compressed "https://apps.beam.cloud/ahg0v" \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Basic [YOUR_AUTH_TOKEN]' \
-H 'Connection: keep-alive' \
-H 'Content-Type: application/json' \
-d '{"prompt": "your prompt"}'
Example Response
{
"result": {
"prediction": "{'POSITIVE': 0.9988627433776855, 'NEGATIVE': 0.0011372779263183475}"
},
"msg": "",
"error_msg": ""
}
Further Reading
Was this page helpful?