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

Move api specs into concepts folder

This commit is contained in:
Aaron Crawfis 2020-03-03 12:52:27 -08:00
parent e96de9d7cc
commit a34aad00f7
10 changed files with 172 additions and 304 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
reference/api/actors.md → concepts/actor/actors_api.md
View File

@ -1,13 +1,34 @@
# Actors
# Dapr Actors API Reference
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.
## Specifications for user service code calling to Dapr
## Endpoints
- [Service Code Calling to Dapr](#specifications-for-user-service-code-calling-to-dapr)
- [Invoke Actor Method](#invoke-actor-method)
- [Save Actor State](#save-actor-state)
- [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)
- [Activate Actor](#activate-actor)
- [Deactivate Actor](#deactivate-actor)
- [Invoke Actor Method](#invoke-actor-method-1)
- [Invoke Reminder](#invoke-reminder)
- [Invoke Timer](#invoke-timer)
- [Querying Actor State Externally](#querying-actor-state-externally)
## User Service Code Calling to Dapr
### Invoke Actor Method
Invokes a method on an actor.
Invoke an actor method through Dapr.
#### HTTP Request
@ -32,14 +53,16 @@ actorType | The actor type.
actorId | The actor ID.
method | The name of the method to invoke.
> Example of invoking a method on an actor:
#### Examples
Example of invoking a method on an actor:
```shell
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/method/shoot \
-H "Content-Type: application/json"
```
> Example of invoking a method on an actor with a payload:
Example of invoking a method on an actor with a payload:
```shell
curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
@ -49,17 +72,17 @@ curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
}'
```
> The response from the remote endpoint will be returned in the request body.
The response from the remote endpoint will be returned in the request body.
### Actor State Changes - Transaction
### Save Actor State
Persists the changed to the state for an actor as a multi-item transaction.
***Note that this operation is dependant on a state store that supports multi-item transactions.***
Persists the changed to the state for an actor
#### HTTP Request
`POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state`
```http
POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state
```
#### HTTP Response Codes
@ -77,6 +100,43 @@ daprPort | The Dapr port.
actorType | The actor type.
actorId | The actor ID.
Value of the key is passed as request body:
```shell
{
"key": "value"
}
```
### Actor State Transactions
Persists the changed to the state for an actor as a multi-item transaction.
***Note that this operation is dependant on a state store that supports multi-item transactions.***
#### HTTP Request
```http
POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state
```
#### HTTP Response Codes
Code | Description
---- | -----------
201 | Request successful
500 | Request failed
404 | Actor not found
#### URL Parameters
Parameter | Description
--------- | -----------
daprPort | The Dapr port.
actorType | The actor type.
actorId | The actor ID.
#### Examples
```shell
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \
-H "Content-Type: application/json"
@ -124,12 +184,14 @@ actorType | The actor type.
actorId | The actor ID.
key | The key for the state value.
#### Examples
```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
-H "Content-Type: application/json"
```
> The above command returns the state:
The above command returns the state:
```json
{
@ -190,6 +252,8 @@ actorType | The actor type.
actorId | The actor ID.
name | The name of the reminder to create.
#### Examples
```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
-H "Content-Type: application/json"
@ -227,12 +291,14 @@ actorType | The actor type.
actorId | The actor ID.
name | The name of the reminder to get.
#### Examples
```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
"Content-Type: application/json"
```
> The above command returns the reminder:
The above command returns the reminder:
```json
{
@ -269,6 +335,8 @@ actorType | The actor type.
actorId | The actor ID.
name | The name of the reminder to delete.
#### Examples
```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
-X "Content-Type: application/json"
@ -319,6 +387,8 @@ actorType | The actor type.
actorId | The actor ID.
name | The name of the timer to create.
#### Examples
```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
-H "Content-Type: application/json"
@ -387,14 +457,16 @@ Parameter | Description
--------- | -----------
appPort | The application port.
> Example of getting the registered actors:
#### Examples
Example of getting the registered actors:
```shell
curl -X GET http://localhost:3000/dapr/config \
-H "Content-Type: application/json"
```
> The above command returns the config (all fields are optional):
The above command returns the config (all fields are optional):
Parameter | Description
@ -441,7 +513,9 @@ appPort | The application port.
actorType | The actor type.
actorId | The actor ID.
> Example of activating an actor:
#### Examples:
Example of activating an actor:
```shell
curl -X POST http://localhost:3000/actors/stormtrooper/50 \
@ -474,7 +548,9 @@ appPort | The application port.
actorType | The actor type.
actorId | The actor ID.
> Example of deactivating an actor:
#### Examples
Example of deactivating an actor:
```shell
curl -X DELETE http://localhost:3000/actors/stormtrooper/50 \
@ -508,7 +584,9 @@ actorType | The actor type.
actorId | The actor ID.
methodName | The name of the method to invoke.
> Example of invoking a method for an actor:
#### Examples
Example of invoking a method for an actor:
```shell
curl -X POST http://localhost:3000/actors/stormtrooper/50/method/performAction \
@ -542,7 +620,9 @@ actorType | The actor type.
actorId | The actor ID.
reminderName | The name of the reminder to invoke.
> Example of invoking a reminder for an actor:
#### Examples
Example of invoking a reminder for an actor:
```shell
curl -X POST http://localhost:3000/actors/stormtrooper/50/method/remind/checkRebels \
@ -576,7 +656,9 @@ actorType | The actor type.
actorId | The actor ID.
timerName | The name of the timer to invoke.
> Example of invoking a timer for an actor:
#### Examples
Example of invoking a timer for an actor:
```shell
curl -X POST http://localhost:3000/actors/stormtrooper/50/method/timer/checkRebels \

25
reference/api/bindings.md → concepts/bindings/bindings_api.md
View File

@ -5,7 +5,15 @@ Developers can invoke output bindings using the Dapr API, and have the Dapr runt
Examples for bindings include ```Kafka```, ```Rabbit MQ```, ```Azure Event Hubs```, ```AWS SQS```, ```GCP Storage``` to name a few.
An Dapr Binding has the following structure:
## 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)
## Bindings Structure
An Dapr Binding yaml file has the following structure:
```yml
apiVersion: dapr.io/v1alpha1
@ -19,12 +27,21 @@ spec:
value: <VALUE>
```
The ```metadata.name``` is the name of the binding. A developer who wants to trigger her app using an input binding can listen on a ```POST``` http endpoint with the route name being the same as ```metadata.name```.
The ```metadata.name``` is the name of the binding.
If running 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.
## Invoking Service Code Through Input Bindings
A developer who wants to trigger her 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.
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 implementation.
### Examples
For example, here's how a Python application subscribes for events from ```Kafka``` using an Dapr API compliant platform:
#### Kafka Component
@ -60,7 +77,7 @@ def incoming():
return "Kafka Event Processed!"
```
## Sending messages to output bindings
## Sending Messages to Output Bindings
This endpoint lets you invoke an Dapr output binding.
@ -100,6 +117,8 @@ Parameter | Description
daprPort | the Dapr port
name | the name of the binding to invoke
### Examples
```shell
curl -X POST http://localhost:3500/v1.0/bindings/myKafka \
-H "Content-Type: application/json" \

0
reference/api/pubsub.md → concepts/publish-subscribe-messaging/pubsub_api.md
View File

9
reference/api/secrets.md → concepts/secrets/secrets_api.md
View File

@ -1,11 +1,10 @@
# Secrets
# Secrets API Specification
Dapr offers developers a consistent way to extract application secrets, without needing to know the specifics of the secret store being used.
Secret stores are components in Dapr. Dapr allows users to write new secret stores implementations that can be used both to hold secrets for other Dapr components (for example secrets used by a state store to read/write state) as well as serving the application with a dedicated secret API. Using the secrets API, you can easily read secrets that can be used by the application from the a named secrets store.
## Endpoints
Some examples for secret stores include `Kubernetes`, `Hashicorp Vault`, `Azure KeyVault`. See [secret stores](https://github.com/dapr/components-contrib/tree/master/secretstores)
- [Get Secret](#get-secret)
## Get secret
## Get Secret
This endpoint lets you get the key-identified value of secret for a given secret store.

33
reference/api/service_invocation.md → concepts/service-invocation/service_invocation_api.md
View File

@ -1,9 +1,13 @@
# Service Invocation
# Service Invocation API Specification
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.
## Invoke a method on a remote Dapr app
## Endpoints
- [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.
@ -28,14 +32,29 @@ daprPort | the Dapr port
appId | the App ID associated with the remote app
method-name | the name of the method or url to invoke on the remote app
```shell
curl http://localhost:3500/v1.0/invoke/countService/method/sum \
-H "Content-Type: application/json"
### Request Contents
In the request you can pass along headers:
```json
{
"Content-Type": "application/json"
}
```
### Sending data
Within the body of the request place the data you want to send to the service:
You can send data by posting it as part of the request body.
```json
{
"arg1": 10,
"arg2": 23,
"operator": "+"
}
```
### Examples
You can invoke the `calculate` method on the countService service by sending the following:
```shell
curl http://localhost:3500/v1.0/invoke/countService/method/calculate \

30
reference/api/state.md → concepts/state-management/state_api.md
View File

@ -1,11 +1,17 @@
# State management
# State Management API Specification
Dapr offers a reliable state endpoint that allows developers to save and retrieve state via an API.
Dapr has a pluggable architecture and allows binding to a multitude of cloud/on-premises state stores.
## Endpoints
- [Component File](#component-file)
- [Key Scheme](#key-scheme)
- [Save State](#save-state)
- [Get State](#get-state)
- [Delete State](#delete-state)
- [Configuring State Store for Actors](#configuring-state-store-for-actors)
- [Optional Behaviors](#optional-behaviors)
Examples for state stores include ```Redis```, ```Azure CosmosDB```, ```AWS DynamoDB```, ```GCP Cloud Spanner```, ```Cassandra``` to name a few.
## Component File
An Dapr State Store has the following structure:
A Dapr State Store component yaml file has the following structure:
```yml
apiVersion: dapr.io/v1alpha1
@ -29,21 +35,21 @@ Starting with 0.4.0 release, support for multiple state stores was added. This i
Please refer https://github.com/dapr/dapr/blob/master/docs/decision_records/api/API-008-multi-state-store-api-design.md for more details.
## Key scheme
## Key Scheme
Dapr state stores are key/value stores. To ensure data compatibility, Dapr requires these data stores follow a fixed key scheme. For general states, the key format is:
```bash
```
<Dapr id>||<state key>
```
For Actor states, the key format is:
```bash
```
<Dapr id>||<Actor type>||<Actor id>||<state key>
```
## Save state
## Save State
This endpoint lets you save an array of state objects.
@ -107,7 +113,7 @@ curl -X POST http://localhost:3500/v1.0/state/starwars \
]'
```
## Get state
## Get State
This endpoint lets you get the state for a specific key.
@ -162,7 +168,7 @@ curl http://localhost:3500/v1.0/state/starwars/planet \
}
```
## Delete state
## Delete State
This endpoint lets you delete the state for a specific key.
@ -233,7 +239,7 @@ spec:
```
## Optional behaviors
## Optional Behaviors
### Key scheme

141
reference/api/CONTRIBUTING.md
View File

@ -1,141 +0,0 @@
# Contributing Guidelines
Thank you for your interest in Dapr!
This project welcomes contributions and suggestions. Most contributions require you to
agree to a Contributor License Agreement (CLA) declaring that you have the right to,
and actually do, grant us the rights to use your contribution.
For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need
to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct.
For more information see the Code of Conduct FAQ
or contact opencode@microsoft.com with any additional questions or comments.
Contributions come in many forms: submitting issues, writing code, participating in discussions and community calls.
This document provides the guidelines for how to contribute to the Dapr project.
## Issues
Issues are used as the primary method for tracking anything to do with the Dapr API Specification project.
### Issue Types
There are 4 types of issues (each with their own corresponding [label](#labels)):
- Discussion: These are support or functionality inquiries that we want to have a record of for
future reference. Depending on the discussion, these can turn into "Spec Change" issues.
- Proposal: Used for items that propose a new ideas or functionality that require
a larger discussion. This allows for feedback from others teams before a
spec change is actually written. All issues that are proposals should
both have a label and an issue title of "Proposal: [the rest of the title]." A proposal can become
a "Spec Change" and does not require a milestone.
- Spec Change: These track specific spec changes and ideas until they are complete. They can evolve
from "Proposal" and "Discussion" items, or can be submitted individually depending on the size.
### Issue Lifecycle
The issue lifecycle is mainly driven by the core maintainers, but is good information for those
contributing to Helm. All issue types follow the same general lifecycle. Differences are noted below.
1. Issue creation
2. Triage
- The maintainer in charge of triaging will apply the proper labels for the issue. This
includes labels for priority, type, and metadata.
- (If needed) Clean up the title to succinctly and clearly state the issue. Also ensure
that proposals are prefaced with "Proposal".
- We attempt to do this process at least once per work day.
3. Discussion
- "Spec Change" issues should be connected to the PR that resolves it.
- Whoever is working on a "Spec Change" issue should either assign the issue to themself or make a comment in the issue
saying that they are taking it.
- "Proposal" and "Discussion" issues should stay open until resolved.
4. Issue closure
## How to Contribute a Patch
1. Fork the repo, modify the specification to address the issue.
2. Submit a pull request.
The next section contains more information on the workflow followed for Pull Requests.
## Pull Requests and Issues
Like any good open source project, we use Pull Requests (PRs) to track code changes.
### PR Lifecycle
1. PR creation
- We more than welcome PRs that are currently in progress. They are a great way to keep track of
important work that is in-flight, but useful for others to see. If a PR is a work in progress,
it **should** be prefaced with "WIP: [title]". You should also add the `wip` **label** Once the PR is ready for review, remove "WIP" from the title and label.
- It is preferred, but not required, to have a PR tied to a specific issue. There can be
circumstances where if it is a quick fix then an issue might be overkill. The details provided
in the PR description would suffice in this case.
2. Triage
- The maintainer in charge of triaging will apply the proper labels for the issue. This should
include at least a size label, a milestone, and `awaiting review` once all labels are applied.
See the [Labels section](#labels) for full details on the definitions of labels.
3. Assigning reviews
- All PRs require at least 2 review approvals before it can be merged.
4. Reviewing/Discussion
- All reviews will be completed using Github review tool.
- A "Comment" review should be used when there are questions about the spec that should be
answered, but that don't involve spec changes. This type of review does not count as approval.
- A "Changes Requested" review indicates that changes to the spec need to be made before they will be
merged.
- Reviewers should update labels as needed (such as `needs rebase`).
- When a review is approved, the reviewer should add `LGTM` as a comment.
- Final approval is required by a designated owner (see `.github/CODEOWNERS` file). Merging is blocked without this final approval. Approvers will factor reviews from all other reviewers into their approval process.
5. PR owner should try to be responsive to comments by answering questions or changing text. Once all comments have been addressed,
the PR is ready to be merged.
6. Merge or close
- A PR should stay open until a Final Approver (see above) has marked the PR approved.
- PRs can be closed by the author without merging
- PRs may be closed by a Final Approver if the decision is made that the PR is not going to be merged
## The Triager
Each week, someone from the Dapr team should act as the triager. This person will be in charge triaging new PRs and issues throughout the day.
## Labels
The following tables define all label types used for the Dapr API Specification. It is split up by category.
### Common
| Label | Description |
| ----- | ----------- |
| `high priority` | Marks an issue or PR as critical. This means that addressing the PR or issue is top priority and will be handled first |
| `duplicate` | Indicates that the issue or PR is a duplicate of another |
| `spec change` | Marks the issue or a PR as an agreed upon change to the spec |
| `wip` | Identifies an issue or PR as a work in progress |
### Issue Specific
| Label | Description |
| ----- | ----------- |
| `proposal` | This issue is a proposal |
| `discussion` | This issue is a question or discussion point to capture feedback |
### PR Specific
| Label | Description |
| ----- | ----------- |
| `awaiting review` | The PR has been triaged and is ready for someone to review |
| `needs rebase` | A helper label used to indicate that the PR needs to be rebased before it can be merged. Used for easy filtering |
#### Size labels
Size labels are used to indicate how much change is in a given PR. This is helpful for estimating review time.
| Label | Description |
| ----- | ----------- |
| `size/small` | Anything less than or equal to 4 files and 150 lines. |
| `size/medium` | Anything greater than `size/small` and less than or equal to 8 files and 300 lines. |
| `size/large` | Anything greater than `size/medium`. This also should be applied to anything that is a significant specification change.

21
reference/api/LICENSE
View File

@ -1,21 +0,0 @@
Copyright (c) Microsoft Corporation.
MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

28
reference/api/README.md
View File

@ -1,28 +0,0 @@
# Dapr API reference
This documentation contains the API reference for the Dapr runtime.
Dapr is an open source runtime that provides a set of building blocks for building scalable distributed apps.
Building blocks include pub/sub, state management, bindings, messaging and invocation, actor runtime capabilities, and more.
Dapr aims to provide an open, community driven approach to solving real world problems at scale.
These building blocks are provided in a platform agnostic and language agnostic way over common protocols such as HTTP 1.1/2.0 and gRPC.
### Goals
The goal of the Dapr API reference is to provide a clear understanding of the Dapr runtime API surface and help evolve it for the benefit of developers everywhere.
Any changes/proposals to the Dapr API should adhere to the following:
* Must be platform agnostic
* Must be programming language agnostic
* Must be backward compatible
## Table of Contents
1. [Service Invocation](service_invocation.md)
2. [Bindings](bindings.md)
3. [Pub Sub/Broadcast](pubsub.md)
4. [State Management](state.md)
5. [Actors](actors.md)

67
reference/api/azure-pipelines.yml
View File

@ -1,67 +0,0 @@
# dapr/spec
trigger:
- master
pr : none
pool:
vmImage: 'ubuntu-latest'
steps:
- task: UseNode@1
inputs:
version: '10.16.3'
- task: Bash@3
displayName: 'Install md-to-pdf'
inputs:
targetType: 'inline'
script: |
npm install -g md-to-pdf
workingDirectory: '$(Build.SourcesDirectory)'
- task: Bash@3
displayName: 'Create pdf output directory'
inputs:
targetType: 'inline'
script: |
mkdir ./output_pdf
mkdir ./output_md
workingDirectory: '$(Build.SourcesDirectory)'
- task: Bash@3
displayName: 'Generate PDF files'
inputs:
targetType: 'inline'
script: |
echo Copying *.md to ./output_md/
cp *.md ./output_md/
pushd ./output_md
rm -f README.md CONTRIBUTING.md
echo Genereating PDFs from markdown documents
for filename in *.md; do
md-to-pdf $filename ../output_pdf/$(basename $filename .md).pdf
done
popd
workingDirectory: '$(Build.SourcesDirectory)'
- task: ArchiveFiles@2
inputs:
rootFolderOrFile: '$(Build.SourcesDirectory)/output_pdf/'
includeRootFolder: false
archiveType: 'zip'
archiveFile: '$(Build.ArtifactStagingDirectory)/dapr-spec-pdf.zip'
replaceExistingArchive: true
- task: ArchiveFiles@2
inputs:
rootFolderOrFile: '$(Build.SourcesDirectory)/output_md/'
includeRootFolder: false
archiveType: 'zip'
archiveFile: '$(Build.ArtifactStagingDirectory)/dapr-spec-md.zip'
replaceExistingArchive: true
- task: PublishBuildArtifacts@1
inputs:
PathtoPublish: '$(Build.ArtifactStagingDirectory)'
ArtifactName: 'drop'
publishLocation: 'Container'