improve API reference consistency #194 (#197)

2019-10-26 16:59:20 +02:00 · 2019-10-26 16:59:20 +02:00 · 86bbb631f4
parent 3be1088380
commit 86bbb631f4
5 changed files with 78 additions and 32 deletions
--- a/reference/api/actors.md
+++ b/reference/api/actors.md
@ -11,7 +11,7 @@ This endpoint lets you invoke a method on a remote Actor.

 #### HTTP Request

-`POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/method/<method>`
+`POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/method/<method>`

 #### HTTP Response codes

@ -25,6 +25,7 @@ Code | Description

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 actorType | the actor type
 actorId | the actor id
 method | the name of the method to invoke on the remote actor
@ -54,7 +55,7 @@ This endpoint lets you save state for a given actor for a given key.

 #### HTTP Request

-`POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>`
+`POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>`

 #### HTTP Response codes

@ -68,6 +69,7 @@ Code | Description

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 actorType | the actor type
 actorId | the actor id
 key | key for the state value
@ -88,7 +90,7 @@ This endpoint lets you save an actor's state as a multi item transaction.

 #### HTTP Request

-`POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state`
+`POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state`

 #### HTTP Response codes

@ -102,6 +104,7 @@ Code | Description

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 actorType | the actor type
 actorId | the actor id

@ -131,7 +134,7 @@ This endpoint lets you get the state of a given actor for a given key.

 #### HTTP Request

-`GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>`
+`GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>`

 #### HTTP Response codes

@ -145,6 +148,7 @@ Code | Description

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 actorType | the actor type
 actorId | the actor id
 key | key for the state value
@ -168,7 +172,7 @@ This endpoint lets you delete the state of a given actor for a given key.

 #### HTTP Request

-`DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>`
+`DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>`

 #### HTTP Response codes

@ -182,6 +186,7 @@ Code | Description

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 actorType | the actor type
 actorId | the actor id
 key | key for the state value
@ -197,7 +202,7 @@ This endpoint lets you create a persistent reminder for an actor.

 #### HTTP Request

-`POST,PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>`
+`POST,PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>`

 #### HTTP Response codes

@ -211,6 +216,7 @@ Code | Description

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 actorType | the actor type
 actorId | the actor id
 name | the name of the reminder
@ -231,7 +237,7 @@ This endpoint lets get a reminder for an actor

 #### HTTP Request

-`GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>`
+`GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>`

 #### HTTP Response codes

@ -245,6 +251,7 @@ Code | Description

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 actorType | the actor type
 actorId | the actor id
 name | the name of the reminder to get
@ -270,7 +277,7 @@ This endpoint lets delete a reminder for an actor

 #### HTTP Request

-`DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>`
+`DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>`

 #### HTTP Response codes

@ -284,6 +291,7 @@ Code | Description

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 actorType | the actor type
 actorId | the actor id
 name | the name of the reminder to delete
@ -299,7 +307,7 @@ This endpoint lets you create a timer for an actor.

 #### HTTP Request

-`POST,PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>`
+`POST,PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>`

 #### HTTP Response codes

@ -313,6 +321,7 @@ Code | Description

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 actorType | the actor type
 actorId | the actor id
 name | the name of the timer
@ -334,7 +343,7 @@ This endpoint lets delete a timer for an actor

 #### HTTP Request

-`DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>`
+`DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>`

 #### HTTP Response codes

@ -348,6 +357,7 @@ Code | Description

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 actorType | the actor type
 actorId | the actor id
 name | the name of the timer to delete
@ -365,7 +375,7 @@ This endpoint lets you get the registered actors in Dapr.

 #### HTTP Request

-`GET http://localhost:<appPort>/v1.0/dapr/config`
+`GET http://localhost:<appPort>/dapr/config`

 #### HTTP Response codes

@ -383,7 +393,7 @@ appPort | the application port
 > Example of getting the registered actors:

 ```shell
-curl -X GET http://localhost:5001/v1.0/dapr/config \
+curl -X GET http://localhost:3000/dapr/config \
 	-H "Content-Type: application/json"
 ```

@ -405,7 +415,7 @@ This endpoint lets you activate the actor.

 #### HTTP Request

-`POST http://localhost:<appPort>/v1.0/actors/<actorType>/<actorId>`
+`POST http://localhost:<appPort>/actors/<actorType>/<actorId>`

 #### HTTP Response codes

@ -426,7 +436,7 @@ actorId | the actor id
 > Example of activating the actor:

 ```shell
-curl -X POST http://localhost:5001/v1.0/actors/stormtrooper/50 \
+curl -X POST http://localhost:3000/actors/stormtrooper/50 \
 	-H "Content-Type: application/json"
 ```

@ -436,7 +446,7 @@ This endpoint lets you deactivate the actor.

 #### HTTP Request

-`DELETE http://localhost:<appPort>/v1.0/actors/<actorType>/<actorId>`
+`DELETE http://localhost:<appPort>/actors/<actorType>/<actorId>`

 #### HTTP Response codes

@ -457,7 +467,7 @@ actorId | the actor id
 > Example of deactivating the actor:

 ```shell
-curl -X DELETE http://localhost:5001/v1.0/actors/stormtrooper/50 \
+curl -X DELETE http://localhost:3000/actors/stormtrooper/50 \
 	-H "Content-Type: application/json"
 ```

@ -467,7 +477,7 @@ This endpoint lets you invokes the actor reminders.

 #### HTTP Request

-`PUT http://localhost:<appPort>/v1.0/actors/<actorType>/<actorId>/method/remind/<reminderName>`
+`PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/remind/<reminderName>`

 #### HTTP Response codes

@ -489,7 +499,7 @@ 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 \
+curl -X POST http://localhost:3000/actors/stormtrooper/50/method/remind/checkRebels \
 	-H "Content-Type: application/json"
 ```

@ -499,7 +509,7 @@ This endpoint lets you invokes the actor timers.

 #### HTTP Request

-`PUT http://localhost:<appPort>/v1.0/actors/<actorType>/<actorId>/method/timer/<timerName>`
+`PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/timer/<timerName>`

 #### HTTP Response codes

@ -521,7 +531,7 @@ 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 \
+curl -X POST http://localhost:3000/actors/stormtrooper/50/method/timer/checkRebels \
 	-H "Content-Type: application/json"
 ```

--- a/reference/api/bindings.md
+++ b/reference/api/bindings.md
@ -64,7 +64,7 @@ This endpoint lets you invoke an Dapr output binding.

 ### HTTP Request

-`POST/GET/PUT/DELETE http://localhost:3500/v1.0/bindings/<name>`
+`POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/bindings/<name>`

 ### HTTP Response codes

@ -93,6 +93,7 @@ The metadata is an array of key/value pairs and allows to set binding specific m

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 name | the name of the binding to invoke

 ```shell
--- a/reference/api/pubsub.md
+++ b/reference/api/pubsub.md
@ -7,7 +7,7 @@ Dapr guarantees at least once semantics for this endpoint.

 ### HTTP Request

-```POST http://localhost:3500/v1.0/publish/<topic>```
+```POST http://localhost:<daprPort>/v1.0/publish/<topic>```
 ### HTTP Response codes

 Code | Description
@ -15,6 +15,13 @@ Code | Description
 200  | Message delivered
 500  | Delivery failed

+### URL Parameters
+
+Parameter | Description
+--------- | -----------
+daprPort | the Dapr port
+topic | the name of the topic
+
 ```shell
 curl -X POST http://localhost:3500/v1.0/publish/deathStarStatus \
 	-H "Content-Type: application/json" \
@ -30,7 +37,7 @@ The list of recipients may include the unique identifiers of other apps (used by

 ### HTTP Request

-```POST http://localhost:3500/v1.0/publish/<topic>```
+```POST http://localhost:<daprPort>/v1.0/publish/<topic>```

 ### HTTP Response codes

@ -39,6 +46,13 @@ Code | Description
 200  | Message delivered
 500  | Delivery failed

+### URL Parameters
+
+Parameter | Description
+--------- | -----------
+daprPort | the Dapr port
+topic | the name of the topic
+
 > Example of publishing a message to another Dapr app:

 ```shell
@ -95,7 +109,13 @@ In order to receive topic subscriptions, Dapr will invoke the following endpoint

 ### HTTP Request

-```GET http://<address>/dapr/subscribe```
+`GET http://localhost:<appPort>/dapr/subscribe`
+
+### URL Parameters
+
+Parameter | Description
+--------- | -----------
+appPort | the application port

 ### HTTP Response body

@ -103,9 +123,9 @@ A json encoded array of strings.

 Example:

-`
+```json
 "["TopicA","TopicB"]"
-`
+```

 ## Delivering events to subscribers

@ -115,7 +135,13 @@ The following example illustrates this point, considering a subscription for top

 ### HTTP Request

-```POST http://<address>/TopicA```
+`POST http://localhost:<appPort>/TopicA`
+
+### URL Parameters
+
+Parameter | Description
+--------- | -----------
+appPort | the application port

 ### HTTP Response body

--- a/reference/api/service_invocation.md
+++ b/reference/api/service_invocation.md
@ -9,7 +9,7 @@ This endpoint lets you invoke a method in another Dapr enabled app.

 ### HTTP Request

-`POST/GET/PUT/DELETE http://localhost:3500/v1.0/invoke/<id>/method/<method-name>`
+`POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<appId>/method/<method-name>`

 ### HTTP Response codes

@ -22,7 +22,8 @@ Code | Description

 Parameter | Description
 --------- | -----------
-id | the App ID associated with the remote app
+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
--- a/reference/api/state.md
+++ b/reference/api/state.md
@ -42,7 +42,13 @@ This endpoint lets you save an array of state objects.

 ### HTTP Request

-`POST http://localhost:3500/v1.0/state`
+`POST http://localhost:<daprPort>/v1.0/state`
+
+#### URL Parameters
+
+Parameter | Description
+--------- | -----------
+daprPort | the Dapr port

 #### Request Body
 A JSON array of state objects. Each state object is comprised with the following fields:
@ -93,12 +99,13 @@ This endpoint lets you get the state for a specific key.

 ### HTTP Request

-`GET http://localhost:3500/v1.0/state/<key>`
+`GET http://localhost:<daprPor>/v1.0/state/<key>`

 #### URL Parameters

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 key | the key of the desired state
 consistency | (optional) read consistency mode, see [state operation options](#state-operation-options)

@ -142,12 +149,13 @@ This endpoint lets you delete the state for a specific key.

 ### HTTP Request

-`DELETE http://localhost:3500/v1.0/state/<key>`
+`DELETE http://localhost:<daprPort>/v1.0/state/<key>`

 #### URL Parameters

 Parameter | Description
 --------- | -----------
+daprPort | the Dapr port
 key | the key of the desired state
 concurrency | (optional) either *first-write* or *last-write*, see [state operation options](#state-operation-options)
 consistency | (optional) either *strong* or *eventual*, see [state operation options](#state-operation-options)