# Actors Dapr has a 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 ### Invoke a method on an Actor This endpoint lets you invoke a method on a remote Actor. #### HTTP Request `POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors///method/` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- actorType | the actor type actorId | the actor id method | the name of the method to invoke on the remote actor > Example of invoking a method on a remote 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 a remote actor with a payload: ```shell curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \ -H "Content-Type: application/json" -d '{ "destination": "Hoth" }' ``` > The response from the remote endpoint will be returned in the request body. ### Save actor state This endpoint lets you save state for a given actor for a given key. #### HTTP Request `POST/PUT http://localhost:3500/v1.0/actors///state/` #### HTTP Response codes Code | Description ---- | ----------- 201 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- actorType | the actor type actorId | the actor id key | key for the state value ```shell curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \ -H "Content-Type: application/json" -d '{ "location": "Alderaan" }' ``` ### Save actor state - transaction This endpoint lets you save an actor's state as a multi item transaction. ***Note that this operation is dependant on a state store that supports multi item transactions.*** #### HTTP Request `POST/PUT http://localhost:3500/v1.0/actors///state` #### HTTP Response codes Code | Description ---- | ----------- 201 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- actorType | the actor type actorId | the actor id ```shell curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \ -H "Content-Type: application/json" -d '[ { "operation": "upsert", "request": { "key": "key1", "value": "myData" } }, { "operation": "delete", "request": { "key": "key2" } } ]' ``` ### Get actor state This endpoint lets you get the state of a given actor for a given key. #### HTTP Request `GET http://localhost:3500/v1.0/actors///state/` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- actorType | the actor type actorId | the actor id key | key for the state value ```shell curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \ -H "Content-Type: application/json" ``` > The above command returns the state: ```json { "location": "Alderaan" } ``` ### Delete actor state This endpoint lets you delete the state of a given actor for a given key. #### HTTP Request `DELETE http://localhost:3500/v1.0/actors///state/` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- actorType | the actor type actorId | the actor id key | key for the state value ```shell curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \ -X "Content-Type: application/json" ``` ### Set actor reminder This endpoint lets you create a persistent reminder for an actor. #### HTTP Request `POST,PUT http://localhost:3500/v1.0/actors///reminders/` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- actorType | the actor type actorId | the actor id name | the name of the reminder ```shell curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \ -H "Content-Type: application/json" -d '{ "data": "someData", "dueTime": "1m", "period": "20s" }' ``` ### Get actor reminder This endpoint lets get a reminder for an actor #### HTTP Request `GET http://localhost:3500/v1.0/actors///reminders/` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- actorType | the actor type actorId | the actor id name | the name of the reminder to get ```shell curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \ "Content-Type: application/json" ``` > The above command returns the reminder: ```json { "dueTime": "1s", "period": "5s", "data": "0", } ``` ### Delete actor reminder This endpoint lets delete a reminder for an actor #### HTTP Request `DELETE http://localhost:3500/v1.0/actors///reminders/` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- actorType | the actor type actorId | the actor id name | the name of the reminder to delete ```shell curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \ -X "Content-Type: application/json" ``` ### Set actor timer This endpoint lets you create a timer for an actor. #### HTTP Request `POST,PUT http://localhost:3500/v1.0/actors///timers/` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- actorType | the actor type actorId | the actor id name | the name of the timer ```shell curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \ -H "Content-Type: application/json" -d '{ "data": "someData", "dueTime": "1m", "period": "20s", "callback": "myEventHandler" }' ``` ### Delete actor timer This endpoint lets delete a timer for an actor #### HTTP Request `DELETE http://localhost:3500/v1.0/actors///timers/` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- actorType | the actor type actorId | the actor id name | the name of the timer to delete ```shell curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \ -X "Content-Type: application/json" ``` ## Specifications for Dapr calling to user service code ### Get Registered Actors This endpoint lets you get the registered actors in Dapr. #### HTTP Request `GET http://localhost:/v1.0/dapr/config` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed #### URL Parameters Parameter | Description --------- | ----------- appPort | the application port > Example of getting the registered actors: ```shell curl -X GET http://localhost:5001/v1.0/dapr/config \ -H "Content-Type: application/json" ``` ### Activate the Actors This endpoint lets you activate the actor. #### HTTP Request `POST http://localhost:/v1.0/actors//` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- appPort | the application port actorType | the actor type actorId | the actor id > Example of activating the actor: ```shell curl -X POST http://localhost:5001/v1.0/actors/stormtrooper/50 \ -H "Content-Type: application/json" ``` ### Deactivate the Actors This endpoint lets you deactivate the actor. #### HTTP Request `DELETE http://localhost:/v1.0/actors//` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- appPort | the application port actorType | the actor type actorId | the actor id > Example of deactivating the actor: ```shell curl -X DELETE http://localhost:5001/v1.0/actors/stormtrooper/50 \ -H "Content-Type: application/json" ``` ### Invoke the Reminders This endpoint lets you invokes the actor reminders. #### HTTP Request `PUT http://localhost:/v1.0/actors///method/remind/` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- appPort | the application port actorType | the actor type actorId | the actor id reminderName | the name of the reminder > Example of invoking the actor reminder: ```shell curl -X POST http://localhost:5001/v1.0/actors/stormtrooper/50/method/remind/checkRebels \ -H "Content-Type: application/json" ``` ### Invoke the Timers This endpoint lets you invokes the actor timers. #### HTTP Request `PUT http://localhost:/v1.0/actors///method/timer/` #### HTTP Response codes Code | Description ---- | ----------- 200 | Request successful 500 | Request failed 404 | Actor not found #### URL Parameters Parameter | Description --------- | ----------- appPort | the application port actorType | the actor type actorId | the actor id timerName | the name of the timer > Example of invoking the actor timer: ```shell curl -X POST http://localhost:5001/v1.0/actors/stormtrooper/50/method/timer/checkRebels \ -H "Content-Type: application/json" ``` ## Querying actor state externally In order to promote visibility into the state of an actor and allow for complex scenarios such as state aggregation, Dapr saves actor state in external 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: * Dapr 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` Dapr ID namespace: `` myapp-cat-hobbit-food `` In the example above, we are getting the value for the state key `food`, for the actor ID `hobbit` with an actor type of `cat`, under the Dapr ID namespace of `myapp`.