Skip to main content

Interacting with Service Endpoints

Once a function service is deployed and in an active state, it exposes the user-defined API. Function services can be interacted with generically or using a Python client with the Covalent Cloud SDK.

This page is about using function services that are already deployed. To learn about deploying new function services, see here.

HTTP Requests​

For example, making a manual request to the /hello endpoint from the first example (defined here) looks like the following with curl.

authorization_token="<paste-real-authorization-token-here>"
curl -X POST "https://fn.prod.covalent.xyz/0663accb6f7d37dbf2a4687b7/hello" \
  -H "x-api-key: $authorization_token" \
  -d '{"number": 1867}'

Here the "number" parameter overrides the number=42 argument in the endpoint’s definition. The received response is therefore:

"Hello, world! My favorite number is 1867"

Live-streaming responses additionally requires setting the --no-buffer/-N flag in curl.

curl -X POST "https://fn.prod.covalent.xyz/0663accb6f7d37dbf2a4687b7/stream" \
  -H "x-api-key: $authorization_token" \
  -d '{"message": "Hello, Covalent!"}' \
  --no-buffer
Hello, Covalent!
Items: 1 5 foo 
Done streaming

Python clients​

There are multiple ways to obtain a Python client for a given deployment.

For instance, the cc.deploy() function returns a client immediately, while the service is most likely still in a CREATING state. In this case, the blocking pattern below can be useful to wait for the ACTIVE state programmatically.

# Reload the client until deployment is active.
example_client = cc.get_deployment(client, wait=True)

We can also obtain a client by passing the function ID string directly:

# Load a client for another deployment by passing an ID.
example_client = cc.get_deployment("663accb6f7d37dbf2a4687b7")

To interact with the service, every client features “endpoint methods” with names that correspond to the route names of attached endpoints.

TIp

Dash characters (-) in route names are replaced by an underscore (_) in the corresponding endpoint method. E.g. the route /custom-endpoint would correspond to the method client.custom_endpoint().

Each call to an endpoint method submits a request to the matching service route. Indeed, running the following reproduces some of the outputs in the previous section.

print(example_client.hello())
print(example_client.hello(number=1867))
print(example_client.hello(message="Hello, Covalent!"))
Hello, world! My favorite number is 42
Hello, world! My favorite number is 1867
Hello, Covalent! My favorite number is 42

Streaming with the Python client requires iterating through the endpoint method’s response. This is only possible with streaming endpoints. Because the stream returns bytes, the output chunks are decoded before printing in the example below.

for b in example_client.stream():
    print(b.decode(), end="")
Hello, world!
Items: 1 5 foo 
Done streaming

Argument overrides work the same way for streaming and non-streaming endpoints: The initializer return values are used by default, unless the user passes arguments with the same name.

for b in example_client.stream(
    message="The quick brown fox jumps over the lazy dog",
    items=list(range(20)),
):
    print(b.decode(), end="")
The quick brown fox jumps over the lazy dog
Items: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 
Done streaming

Tip

Endpoint methods on Python clients accept only keyword arguments!