mirror of https://github.com/dapr/docs.git
Updating the HTTP binding documentation … (#1174)
* fixed typo in Service invocation overview (#1170) * Updating the HTTP binding documentation per PR dapr/components-contrib/pull/661 * Adding extra status info returned by the refactored HTTP binding * Tweaks per PR * Update http.md * Formatting tweaks Co-authored-by: Patrick de Mooij <patrickdemooij@gmail.com> Co-authored-by: Mark Fussell <mfussell@microsoft.com>
This commit is contained in:
Phil Kedy
GitHub
parent
dfc0555291
commit
c6f708fe83
|
|
@ -108,7 +108,7 @@ The diagram below shows sequence 1-7 again on a local machine showing the API ca
|
|||
4. The Node.js app's sidecar forwards the request to the Node.js app. The Node.js app performs its business logic, logging the incoming message and then persist the order ID into Redis (not shown in the diagram)
|
||||
5. The Node.js app sends a response to the Python app through the Node.js sidecar.
|
||||
6. Dapr forwards the response to the Python Dapr sidecar
|
||||
7. The Python app receives the resposne.
|
||||
7. The Python app receives the response.
|
||||
|
||||
## Next steps
|
||||
|
||||
|
|
|
|||
|
|
@ -19,19 +19,157 @@ spec:
|
|||
metadata:
|
||||
- name: url
|
||||
value: http://something.com
|
||||
- name: method
|
||||
value: GET
|
||||
```
|
||||
|
||||
- `url` is the HTTP url to invoke.
|
||||
- `method` is the HTTP verb to use for the request.
|
||||
## Spec metadata fields
|
||||
|
||||
## Output Binding Supported Operations
|
||||
| Field | Required | Details | Example |
|
||||
|--------------------|:--------:|---------|---------|
|
||||
| url | Y | The base URL of the HTTP endpoint to invoke | `http://host:port/path`, `http://myservice:8000/customers`
|
||||
|
||||
* create
|
||||
## Output binding supported operations
|
||||
|
||||
The HTTP output binding supports using the following [HTTP methods/verbs](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html)
|
||||
|
||||
| Operation | Description |
|
||||
|------------------------|-------------|
|
||||
| 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 |
|
||||
| create | For backward compatability and treated like a post |
|
||||
| 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
|
||||
|
||||
| Field | Required | Details | Example |
|
||||
|--------------------|:--------:|---------|---------|
|
||||
| path | N | The path to append to the base URL. Used for accessing specific URIs | `"/1234"`, `"/search?lastName=Jones"`
|
||||
| Headers* | N | Any 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "get"
|
||||
}
|
||||
```
|
||||
|
||||
Optionally, a path can be specified to interact with resource URIs:
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "get",
|
||||
"metadata": {
|
||||
"path": "/things/1234"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
| Field | Required | Details | Example |
|
||||
|--------------------|:--------:|---------|---------|
|
||||
| statusCode | Y | The [HTTP status code](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) | `200`, `404`, `503`
|
||||
| status | Y | The status description | `"200 OK"`, `"201 Created"`
|
||||
| Headers* | N | Any fields that have a capital first letter are sent as request headers | `"Content-Type"`
|
||||
|
||||
#### Example
|
||||
|
||||
**Requesting the base URL**
|
||||
|
||||
{{< tabs Windows Linux >}}
|
||||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d "{ \"operation\": \"get\" }" \
|
||||
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d '{ "operation": "get" }' \
|
||||
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
**Requesting a specific path**
|
||||
|
||||
{{< tabs Windows Linux >}}
|
||||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d "{ \"operation\": \"get\", \"metadata\": { \"path\": \"/things/1234\" } }" \
|
||||
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d '{ "operation": "get", "metadata": { "path": "/things/1234" } }' \
|
||||
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
### 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:
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
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 overriden be setting the `Content-Type` metadata field.
|
||||
{{% /alert %}}
|
||||
|
||||
```json
|
||||
{
|
||||
"operation": "post",
|
||||
"data": "content (default is JSON)",
|
||||
"metadata": {
|
||||
"path": "/things",
|
||||
"Content-Type": "application/json; charset=utf-8"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Example
|
||||
|
||||
**Posting a new record**
|
||||
|
||||
{{< tabs Windows Linux >}}
|
||||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d "{ \"operation\": \"post\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"path\": \"/things\" } }" \
|
||||
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
```bash
|
||||
curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "path": "/things" } }' \
|
||||
http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Related links
|
||||
- [Bindings building block]({{< ref bindings >}})
|
||||
- [How-To: Trigger application with input binding]({{< ref howto-triggers.md >}})
|
||||
- [How-To: Use bindings to interface with external resources]({{< ref howto-bindings.md >}})
|
||||
- [Bindings API reference]({{< ref bindings_api.md >}})
|
||||
- [Bindings API reference]({{< ref bindings_api.md >}})
|
||||
|
|
|
|||
Loading…
Reference in New Issue