HTTP binding spec

    Spec metadata fields

    This component supports output binding with the following :

    • create : For backward compatibility and treated like a post
    • get : Read data/records
    • head : Identical to get except that the server does not return a response body
    • post : Typically used to create records or send commands
    • put : Update data/records
    • patch : Sometimes used to update a subset of fields of a record
    • delete : Delete a data/record
    • options : Requests for information about the communication options available (not commonly used)
    • trace : Used to invoke a remote, application-layer loop- back of the request message (not commonly used)

    Operation metadata fields

    All of the operations above support the following metadata fields

    Retrieving data

    To retrieve data from the HTTP endpoint, invoke the HTTP binding with a GET method and the following JSON body:

    1. {
    2.   "operation": "get"
    3. }

    Optionally, a path can be specified to interact with resource URIs:

    1. {
    2.   "operation": "get",
    3.   "metadata": {
    4.     "path": "/things/1234"
    5.   }
    6. }

    The response body contains the data returned by the HTTP endpoint. The data field contains the HTTP response body as a byte slice (Base64 encoded via curl). The metadata field contains:

    Example

    1. curl -d "{ \"operation\": \"get\" }" \
    1. curl -d '{ "operation": "get" }' \

    Requesting a specific path

    1. curl -d '{ "operation": "get", "metadata": { "path": "/things/1234" } }' \
    2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

    To send data to the HTTP endpoint, invoke the HTTP binding with a POST, PUT, or PATCH method and the following JSON body:

    Note

    Any metadata field that starts with a capital letter is passed as a request header. For example, the default content type is application/json; charset=utf-8. This can be overridden be setting the Content-Type metadata field.

    1. {
    2.   "operation": "post",
    3.   "data": "content (default is JSON)",
    4.   "metadata": {
    5.     "path": "/things",
    6.     "Content-Type": "application/json; charset=utf-8"
    7.   }
    8. }

    Example

    Posting a new record

    1. curl -d "{ \"operation\": \"post\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"path\": \"/things\" } }" \
    2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
    1. curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "path": "/things" } }' \
    2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

    Using HTTPS

    The HTTP binding can also be used with HTTPS endpoints by configuring the Dapr sidecar to trust the server’s SSL certificate.

    1. Update the binding URL to use https instead of http.
    2. Refer , to install the SSL certificate in the sidecar.

    Update the binding component

    Install the SSL certificate in the sidecar

    Below is an example when the sidecar is running as a container. The SSL certificate is located on the host computer at /tmp/ssl/cert.pem.

    1. version: '3'
    2. services:
    3.   my-app:
    4.     # ...
    5.   dapr-sidecar:
    6.     image: "daprio/daprd:1.8.0"
    7.     command: [
    8.       "./daprd",
    9.      "-app-id", "myapp",
    10.      "-app-port", "3000",
    11.      ]
    12.     volumes:
    13.         - "./components/:/components"
    14.         - "/tmp/ssl/:/certificates" # Mount the certificates folder to the sidecar container at /certificates
    15.     environment:
    17.       - my-app

    The sidecar can read the SSL certificate from a variety of sources. See for more. In this example, we store the SSL certificate as a Kubernetes secret.

    1. kubectl create secret generic myapp-cert --from-file /tmp/ssl/cert.pem

    The YAML below is an example of the Kubernetes deployment that mounts the above secret to the sidecar and sets SSL_CERT_DIR to install the certificates.

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: myapp
    5.   namespace: default
    6.   labels:
    7.     app: myapp
    8. spec:
    9.   replicas: 1
    10.   selector:
    11.     matchLabels:
    12.       app: myapp
    13.   template:
    14.     metadata:
    15.       labels:
    16.         app: myapp
    17.       annotations:
    18.         dapr.io/enabled: "true"
    19.         dapr.io/app-id: "myapp"
    20.         dapr.io/app-port: "8000"
    21.         dapr.io/volume-mounts: "cert-vol:/certificates" # Mount the certificates folder to the sidecar container at /certificates
    22.         dapr.io/env: "SSL_CERT_DIR=/certificates" # Set the environment variable to the path of the certificates folder
    23.     spec:
    24.       volumes:
    25.         - name: cert-vol
    26.           secret:
    27.             secretName: myapp-cert
    28. ...

    Invoke the binding securely

    1. curl -d "{ \"operation\": \"get\" }" \
    2.       https://localhost:<dapr-port>/v1.0/bindings/<binding-name>

    You can configure the HTTP binding to use mTLS or client TLS authentication along with HTTPS by providing the MTLSRootCA, MTLSClientCert, and MTLSClientKey metadata fields in the binding component.

    These fields can be passed as a file path or as a pem encoded string.

    • If the file path is provided, the file is read and the contents are used.
    • If the pem encoded string is provided, the string is used as is. When these fields are configured, the Dapr sidecar uses the provided certificate to authenticate itself with the server during the TLS handshake process.