HTTP binding spec

Detailed documentation on the HTTP binding component

Setup Dapr component

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4. name: <NAME>
  5. namespace: <NAMESPACE>
  6. spec:
  7. type: bindings.http
  8. version: v1
  9. metadata:
  10. - name: url
  11. value: http://something.com

Spec metadata fields

FieldRequiredBinding supportDetailsExample
urlYOutputThe base URL of the HTTP endpoint to invokehttp://host:port/path, http://myservice:8000/customers

Binding support

This component supports output binding with the following HTTP methods/verbs:

  • 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)

Request

Operation metadata fields

All of the operations above support the following metadata fields

FieldRequiredDetailsExample
pathNThe path to append to the base URL. Used for accessing specific URIs“/1234”, “/search?lastName=Jones”
Headers*NAny fields that have a capital first letter are sent as request headers“Content-Type”, “Accept”

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. }

Response

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:

FieldRequiredDetailsExample
statusCodeYThe HTTP status code200, 404, 503
statusYThe status description“200 OK”, “201 Created”
Headers*NAny fields that have a capital first letter are sent as request headers“Content-Type”

Example

Requesting the base URL

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

Requesting a specific path

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

Sending and updating data

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>

Last modified February 18, 2022: Update setup-jetstream.md (#2200) (428d8c2)