dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

API reference

This commit is contained in:
Aaron Crawfis 2020-10-15 14:42:07 -07:00
parent d5ddbeb453
commit 587c77ff2f
9 changed files with 155 additions and 148 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
daprdocs/content/en/reference/api/_index.md
View File

@ -2,8 +2,6 @@
type: docs
title: Dapr API reference
linkTitle: "Dapr API"
weight: 100
description: "Information on each api, the associated endpoints, and what capabilities are available"
---
Dapr is language agnostic and provides a RESTful HTTP & gRPC API.
The documents in this folder outline each api, the associated endpoints, and what capabilities are available.

67
daprdocs/content/en/reference/api/actors_api.md
View File

@ -1,28 +1,14 @@
# Dapr actors API reference
---
type: docs
title: "Actors API reference"
linkTitle: "Actors API"
description: "Detailed documentation on the actors API"
weight: 500
---
Dapr provides native, cross-platform and cross-language virtual actor capabilities.
Besides the language specific Dapr SDKs, a developer can invoke an actor using the API endpoints below.
## Endpoints
- [Service Code Calling to Dapr](#specifications-for-user-service-code-calling-to-dapr)
- [Invoke Actor Method](#invoke-actor-method)
- [Actor State Transactions](#actor-state-transactions)
- [Get Actor State](#get-actor-state)
- [Create Actor Reminder](#create-actor-reminder)
- [Get Actor Reminder](#get-actor-reminder)
- [Delete Actor Reminder](#delete-actor-reminder)
- [Create Actor Timer](#create-actor-timer)
- [Delete Actor Timer](#delete-actor-timer)
- [Dapr Calling to Service Code](#specifications-for-dapr-calling-to-user-service-code)
- [Get Registered Actors](#get-registered-actors)
- [Deactivate Actor](#deactivate-actor)
- [Invoke Actor Method](#invoke-actor-method-1)
- [Invoke Reminder](#invoke-reminder)
- [Invoke Timer](#invoke-timer)
- [Health Checks](#health-check)
- [Querying Actor State Externally](#querying-actor-state-externally)
## User service code calling dapr
### Invoke actor method
@ -31,7 +17,7 @@ Invoke an actor method through Dapr.
#### HTTP Request
```http
```
POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/method/<method>
```
@ -90,7 +76,7 @@ Persists the changed to the state for an actor as a multi-item transaction.
#### HTTP Request
```http
```
POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state
```
@ -142,7 +128,7 @@ Gets the state for an actor using a specified key.
#### HTTP Request
```http
```
GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>
```
@ -188,8 +174,8 @@ Creates a persistent reminder for an actor.
#### HTTP Request
```http
POST,PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
Body:
@ -255,7 +241,7 @@ Gets a reminder for an actor.
#### HTTP Request
```http
```
GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
@ -301,7 +287,7 @@ Deletes a reminder for an actor.
#### HTTP Request
```http
```
DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
@ -337,8 +323,8 @@ Creates a timer for an actor.
#### HTTP Request
```http
POST,PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>
```
POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>
```
Body:
@ -433,7 +419,7 @@ Gets the registered actors types for this app and the Dapr actor configuration s
#### HTTP Request
```http
```
GET http://localhost:<appPort>/dapr/config
```
@ -486,7 +472,7 @@ Deactivates an actor by persisting the instance of the actor to the state store
#### HTTP Request
```http
```
DELETE http://localhost:<appPort>/actors/<actorType>/<actorId>
```
@ -523,7 +509,7 @@ Invokes a method for an actor with the specified methodName where parameters to
#### HTTP Request
```http
```
PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/<methodName>
```
@ -561,7 +547,7 @@ Invokes a reminder for an actor with the specified reminderName. If the actor i
#### HTTP Request
```http
```
PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/remind/<reminderName>
```
@ -599,7 +585,7 @@ Invokes a timer for an actor rwith the specified timerName. If the actor is not
#### HTTP Request
```http
```
PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/timer/<timerName>
```
@ -640,7 +626,7 @@ A response body is not required.
#### HTTP Request
```http
```
GET http://localhost:<appPort>/healthz
```
@ -673,11 +659,10 @@ Conceptually, activating an actor means creating the actor's object and adding
In order to enable visibility into the state of an actor and allow for complex scenarios such as state aggregation, Dapr saves actor state in external state stores such as databases. As such, it is possible to query for an actor state externally by composing the correct key or query.
The state namespace created by Dapr for actors is composed of the following items:
* App ID - Represents the unique ID given to the Dapr application.
* Actor Type - Represents the type of the actor.
* Actor ID - Represents the unique ID of the actor instance for an actor type.
* Key - A key for the specific state value. An actor ID can hold multiple state keys.
- App ID - Represents the unique ID given to the Dapr application.
- Actor Type - Represents the type of the actor.
- Actor ID - Represents the unique ID of the actor instance for an actor type.
- Key - A key for the specific state value. An actor ID can hold multiple state keys.
The following example shows how to construct a key for the state of an actor instance under the `myapp` App ID namespace:
`myapp-cat-hobbit-food`

40
daprdocs/content/en/reference/api/bindings_api.md
View File

@ -1,15 +1,15 @@
# Bindings
---
type: docs
title: "Bindings API reference"
linkTitle: "Bindings API"
description: "Detailed documentation on the bindings API"
weight: 400
---
Dapr provides bi-directional binding capabilities for applications and a consistent approach to interacting with different cloud/on-premise services or systems.
Developers can invoke output bindings using the Dapr API, and have the Dapr runtime trigger an application with input bindings.
Examples for bindings include ```Kafka```, ```Rabbit MQ```, ```Azure Event Hubs```, ```AWS SQS```, ```GCP Storage``` to name a few.
## Contents
- [Bindings Structure](#bindings-structure)
- [Invoking Service Code Through Input Bindings](#invoking-service-code-through-input-bindings)
- [Sending Messages to Output Bindings](#sending-messages-to-output-bindings)
Examples for bindings include `Kafka`, `Rabbit MQ`, `Azure Event Hubs`, `AWS SQS`, `GCP Storage` to name a few.
## Bindings Structure
@ -28,25 +28,25 @@ spec:
value: <VALUE>
```
The ```metadata.name``` is the name of the binding.
The `metadata.name` is the name of the binding.
If running self hosted locally, place this file in your `components` folder next to your state store and message queue yml configurations.
If running on kubernetes apply the component to your cluster.
> **Note:** In production never place passwords or secrets within Dapr component files. For information on securely storing and retrieving secrets using secret stores refer to [Setup Secret Store](../../howto/setup-secret-store)
> **Note:** In production never place passwords or secrets within Dapr component files. For information on securely storing and retrieving secrets using secret stores refer to [Setup Secret Store]({{< ref setup-secret-store >}})
## Invoking Service Code Through Input Bindings
A developer who wants to trigger their app using an input binding can listen on a ```POST``` http endpoint with the route name being the same as ```metadata.name```.
A developer who wants to trigger their app using an input binding can listen on a `POST` http endpoint with the route name being the same as `metadata.name`.
On startup Dapr sends a ```OPTIONS``` request to the ```metadata.name``` endpoint and expects a different status code as ```NOT FOUND (404)``` if this application wants to subscribe to the binding.
On startup Dapr sends a `OPTIONS` request to the `metadata.name` endpoint and expects a different status code as `NOT FOUND (404)` if this application wants to subscribe to the binding.
The ```metadata``` section is an open key/value metadata pair that allows a binding to define connection properties, as well as custom properties unique to the component implementation.
The `metadata` section is an open key/value metadata pair that allows a binding to define connection properties, as well as custom properties unique to the component implementation.
### Examples
For example, here's how a Python application subscribes for events from ```Kafka``` using a Dapr API compliant platform. Note how the metadata.name value `kafkaevent` in the components matches the POST route name in the Python code.
For example, here's how a Python application subscribes for events from `Kafka` using a Dapr API compliant platform. Note how the metadata.name value `kafkaevent` in the components matches the POST route name in the Python code.
#### Kafka Component
@ -88,7 +88,7 @@ Bindings are discovered from component yaml files. Dapr calls this endpoint on s
#### HTTP Request
```http
```
OPTIONS http://localhost:<appPort>/<name>
```
@ -114,7 +114,7 @@ In order to deliver binding inputs, a POST call is made to user code with the na
#### HTTP Request
```http
```
POST http://localhost:<appPort>/<name>
```
@ -138,9 +138,9 @@ name | the name of the binding
Optionally, a response body can be used to directly bind input bindings with state stores or output bindings.
**Example:**
Dapr stores ```stateDataToStore``` into a state store named "stateStore".
Dapr sends ```jsonObject``` to the output bindings named "storage" and "queue" in parallel.
If ```concurrency``` is not set, it is sent out sequential (the example below shows these operations are done in parallel)
Dapr stores `stateDataToStore` into a state store named "stateStore".
Dapr sends `jsonObject` to the output bindings named "storage" and "queue" in parallel.
If `concurrency` is not set, it is sent out sequential (the example below shows these operations are done in parallel)
```json
{
@ -162,7 +162,7 @@ See the [different specs](../specs/bindings) on each binding to see the list of
### HTTP Request
```http
```
POST/PUT http://localhost:<daprPort>/v1.0/bindings/<name>
```

62
daprdocs/content/en/reference/api/error_codes.md
View File

@ -1,4 +1,10 @@
# Error Codes returned by APIs
---
type: docs
title: "Error codes returned by APIs"
linkTitle: "Error codes"
description: "Detailed reference of the Dapr API error codes"
weight: 1000
---
For http calls made to Dapr runtime, when an error is encountered, an error json is returned in http response body. The json contains an error code and an descriptive error message, e.g.
```
@ -10,30 +16,30 @@ For http calls made to Dapr runtime, when an error is encountered, an error json
Following table lists the error codes returned by Dapr runtime:
Error Code | Description
--------- | -----------
ERR_ACTOR_INSTANCE_MISSING | Error getting an actor instance. This means that actor is now hosted in some other service replica.
ERR_ACTOR_RUNTIME_NOT_FOUND | Error getting the actor instance.
ERR_ACTOR_REMINDER_CREATE | Error creating a reminder for an actor.
ERR_ACTOR_REMINDER_DELETE | Error deleting a reminder for an actor.
ERR_ACTOR_TIMER_CREATE | Error creating a timer for an actor.
ERR_ACTOR_TIMER_DELETE | Error deleting a timer for an actor.
ERR_ACTOR_REMINDER_GET | Error getting a reminder for an actor.
ERR_ACTOR_INVOKE_METHOD | Error invoking a method on an actor.
ERR_ACTOR_STATE_DELETE | Error deleting the state for an actor.
ERR_ACTOR_STATE_GET | Error getting the state for an actor.
ERR_ACTOR_STATE_TRANSACTION_SAVE | Error storing actor state transactionally.
ERR_PUBSUB_NOT_FOUND | Error referencing the Pub/Sub component in Dapr runtime.
ERR_PUBSUB_PUBLISH_MESSAGE | Error publishing a message.
ERR_PUBSUB_CLOUD_EVENTS_SER | Error serializing Pub/Sub event envelope.
ERR_STATE_STORE_NOT_FOUND | Error referencing a state store not found.
ERR_STATE_GET | Error getting a state for state store.
ERR_STATE_DELETE | Error deleting a state from state store.
ERR_STATE_SAVE | Error saving a state in state store.
ERR_INVOKE_OUTPUT_BINDING | Error invoking an output binding.
ERR_MALFORMED_REQUEST | Error with a malformed request.
ERR_DIRECT_INVOKE | Error in direct invocation.
ERR_DESERIALIZE_HTTP_BODY | Error deserializing an HTTP request body.
ERR_SECRET_STORE_NOT_CONFIGURED| Error that no secret store is configured.
ERR_SECRET_STORE_NOT_FOUND | Error that specified secret store is not found.
ERR_HEALTH_NOT_READY | Error that Dapr is not ready.
| Error Code | Description |
|----------------------------------|-------------|
| ERR_ACTOR_INSTANCE_MISSING | Error getting an actor instance. This means that actor is now hosted in some other service replica.
| ERR_ACTOR_RUNTIME_NOT_FOUND | Error getting the actor instance.
| ERR_ACTOR_REMINDER_CREATE | Error creating a reminder for an actor.
| ERR_ACTOR_REMINDER_DELETE | Error deleting a reminder for an actor.
| ERR_ACTOR_TIMER_CREATE | Error creating a timer for an actor.
| ERR_ACTOR_TIMER_DELETE | Error deleting a timer for an actor.
| ERR_ACTOR_REMINDER_GET | Error getting a reminder for an actor.
| ERR_ACTOR_INVOKE_METHOD | Error invoking a method on an actor.
| ERR_ACTOR_STATE_DELETE | Error deleting the state for an actor.
| ERR_ACTOR_STATE_GET | Error getting the state for an actor.
| ERR_ACTOR_STATE_TRANSACTION_SAVE | Error storing actor state transactionally.
| ERR_PUBSUB_NOT_FOUND | Error referencing the Pub/Sub component in Dapr runtime.
| ERR_PUBSUB_PUBLISH_MESSAGE | Error publishing a message.
| ERR_PUBSUB_CLOUD_EVENTS_SER | Error serializing Pub/Sub event envelope.
| ERR_STATE_STORE_NOT_FOUND | Error referencing a state store not found.
| ERR_STATE_GET | Error getting a state for state store.
| ERR_STATE_DELETE | Error deleting a state from state store.
| ERR_STATE_SAVE | Error saving a state in state store.
| ERR_INVOKE_OUTPUT_BINDING | Error invoking an output binding.
| ERR_MALFORMED_REQUEST | Error with a malformed request.
| ERR_DIRECT_INVOKE | Error in direct invocation.
| ERR_DESERIALIZE_HTTP_BODY | Error deserializing an HTTP request body.
| ERR_SECRET_STORE_NOT_CONFIGURED | Error that no secret store is configured.
| ERR_SECRET_STORE_NOT_FOUND | Error that specified secret store is not found.
| ERR_HEALTH_NOT_READY | Error that Dapr is not ready.

18
daprdocs/content/en/reference/api/health_api.md
View File

@ -1,31 +1,37 @@
# Dapr health API reference
---
type: docs
title: "Health API reference"
linkTitle: "Health API"
description: "Detailed documentation on the health API"
weight: 900
---
Dapr provides health checking probes that can be used as readiness or liveness of Dapr.
### Get Dapr health state
## Get Dapr health state
Gets the health state for Dapr.
#### HTTP Request
### HTTP Request
```http
GET http://localhost:<daprPort>/v1.0/healthz
```
#### HTTP Response Codes
### HTTP Response Codes
Code | Description
---- | -----------
200 | dapr is healthy
500 | dapr is not healthy
#### URL Parameters
### URL Parameters
Parameter | Description
--------- | -----------
daprPort | The Dapr port.
#### Examples
### Examples
```shell
curl http://localhost:3500/v1.0/healthz

38
daprdocs/content/en/reference/api/pubsub_api.md
View File

@ -1,13 +1,19 @@
# Pub Sub
---
type: docs
title: "Pub/sub API reference"
linkTitle: "Pub/Sub API"
description: "Detailed documentation on the pub/sub API"
weight: 300
---
## Publish a message to a given topic
This endpoint lets you publish data to multiple consumers who are listening on a ```topic```.
This endpoint lets you publish data to multiple consumers who are listening on a `topic`.
Dapr guarantees at least once semantics for this endpoint.
### HTTP Request
```http
```
POST http://localhost:<daprPort>/v1.0/publish/<pubsubname>/<topic>
```
@ -36,25 +42,25 @@ curl -X POST http://localhost:3500/v1.0/publish/pubsubName/deathStarStatus \
}'
```
# Optional Application (User Code) Routes
## Optional Application (User Code) Routes
## Provide a route for Dapr to discover topic subscriptions
### Provide a route for Dapr to discover topic subscriptions
Dapr will invoke the following endpoint on user code to discover topic subscriptions:
### HTTP Request
#### HTTP Request
```http
```
GET http://localhost:<appPort>/dapr/subscribe
```
### URL Parameters
#### URL Parameters
Parameter | Description
--------- | -----------
appPort | the application port
### HTTP Response body
#### HTTP Response body
A json encoded array of strings.
@ -72,28 +78,28 @@ Example:
> Note, all subscription parameters are case-sensitive.
## Provide route(s) for Dapr to deliver topic events
### Provide route(s) for Dapr to deliver topic events
In order to deliver topic events, a `POST` call will be made to user code with the route specified in the subscription response.
The following example illustrates this point, considering a subscription for topic `newOrder` with route `orders` on port 3000: `POST http://localhost:3000/orders`
### HTTP Request
#### HTTP Request
```http
```
POST http://localhost:<appPort>/<path>
```
> Note, all URL parameters are case-sensitive.
### URL Parameters
#### URL Parameters
Parameter | Description
--------- | -----------
appPort | the application port
path | route path from the subscription configuration
### Expected HTTP Response
#### Expected HTTP Response
An HTTP 200 response with JSON encoded payload body with the processing status:
@ -120,11 +126,11 @@ HTTP Status | Description
other | warning is logged and message to be retried
## Message Envelope
## Message envelope
Dapr Pub/Sub adheres to version 1.0 of Cloud Events.
## Related links
* [How to consume topics](https://github.com/dapr/docs/tree/master/howto/consume-topic)
* [How to publish to and consume topics]({{< ref howto-publish-subscribe.md >}})
* [Sample for pub/sub](https://github.com/dapr/quickstarts/tree/master/pub-sub)

16
daprdocs/content/en/reference/api/secrets_api.md
View File

@ -1,8 +1,10 @@
# Secrets API Specification
## Endpoints
- [Get Secret](#get-secret)
---
type: docs
title: "Secrets API reference"
linkTitle: "Secrets API"
description: "Detailed documentation on the secrets API"
weight: 700
---
## Get Secret
@ -10,7 +12,7 @@ This endpoint lets you get the value of a secret for a given secret store.
### HTTP Request
```http
```
GET http://localhost:<daprPort>/v1.0/secrets/<secret-store-name>/<name>
```
@ -28,7 +30,7 @@ name | the name of the secret to get
Some secret stores have **optional** metadata properties. metadata is populated using query parameters:
```http
```
GET http://localhost:<daprPort>/v1.0/secrets/<secret-store-name>/<name>?metadata.version_id=15
```

19
daprdocs/content/en/reference/api/service_invocation_api.md
View File

@ -1,19 +1,21 @@
# Service Invocation API Specification
---
type: docs
title: "Service invocation API reference"
linkTitle: "Service invocation API"
description: "Detailed documentation on the service invocation API"
weight: 100
---
Dapr provides users with the ability to call other applications that have unique ids.
This functionality allows apps to interact with one another via named identifiers and puts the burden of service discovery on the Dapr runtime.
## Contents
- [Invoke a Method on a Remote Dapr App](#invoke-a-method-on-a-remote-dapr-app)
## Invoke a method on a remote dapr app
This endpoint lets you invoke a method in another Dapr enabled app.
### HTTP Request
```http
```
POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<appId>/method/<method-name>
```
@ -75,7 +77,7 @@ myApp.production
#### Namespace supported platforms
* Kubernetes
- Kubernetes
### Examples
@ -114,3 +116,6 @@ In case you are invoking `mathService` on a different namespace, you can use the
`http://localhost:3500/v1.0/invoke/mathService.testing/method/api/v1/add`
In this URL, `testing` is the namespace that `mathService` is running in.
## Next Steps
- [How-To: Invoke and discover services]({{< ref howto-invoke-discover-services.md >}})

37
daprdocs/content/en/reference/api/state_api.md
View File

@ -1,15 +1,10 @@
# State Management API Specification
## Endpoints
- [Component File](#component-file)
- [Key Scheme](#key-scheme)
- [Save State](#save-state)
- [Get State](#get-state)
- [Get Bulk State](#get-bulk-state)
- [Delete State](#delete-state)
- [State transactions](#state-transactions)
- [Configuring State Store for Actors](#configuring-state-store-for-actors)
- [Optional Behaviors](#optional-behaviors)
---
type: docs
title: "State management API reference"
linkTitle: "State management API"
description: "Detailed documentation on the state management API"
weight: 200
---
## Component file
@ -58,7 +53,7 @@ This endpoint lets you save an array of state objects.
### HTTP Request
```http
```
POST http://localhost:<daprPort>/v1.0/state/<storename>
```
@ -124,7 +119,7 @@ This endpoint lets you get the state for a specific key.
### HTTP Request
```http
```
GET http://localhost:<daprPort>/v1.0/state/<storename>/<key>
```
@ -177,7 +172,7 @@ curl http://localhost:3500/v1.0/state/starwars/planet \
To pass metadata as query parammeter:
```http
```
GET http://localhost:3500/v1.0/state/starwars/planet?metadata.partitionKey=mypartitionKey
```
@ -187,7 +182,7 @@ This endpoint lets you get a list of values for a given list of keys.
### HTTP Request
```http
```
POST http://localhost:<daprPort>/v1.0/state/<storename>/bulk
```
@ -243,7 +238,7 @@ curl http://localhost:3500/v1.0/state/myRedisStore/bulk \
```
To pass metadata as query parammeter:
```http
```
POST http://localhost:3500/v1.0/state/myRedisStore/bulk?metadata.partitionKey=mypartitionKey
```
@ -254,7 +249,7 @@ This endpoint lets you delete the state for a specific key.
### HTTP Request
```http
```
DELETE http://localhost:<daprPort>/v1.0/state/<storename>/<key>
```
@ -311,7 +306,7 @@ List of state stores that support transactions:
#### HTTP Request
```http
```
POST/PUT http://localhost:<daprPort>/v1.0/state/<storename>/transaction
```
@ -456,3 +451,7 @@ curl -X POST http://localhost:3500/v1.0/state/starwars \
}
]'
```
## Next Steps
- [State management overview]({{< ref state-management-overview.md >}})
- [How-To: Save & get state]({{< ref howto-get-save-state.md >}})