csantanapr commented on a change in pull request #3352: API GW doc update to
include path parameter example
URL:
https://github.com/apache/incubator-openwhisk/pull/3352#discussion_r170764261
##########
File path: docs/apigateway.md
##########
@@ -104,52 +103,61 @@ You have a series of actions to implement your backend
for the book club:
| putBooks | PUT | updates book details |
| deleteBooks | DELETE | deletes a book |
-Let's create an API for the book club, named `Book Club`, with `/club` as its
HTTP URL base path and `books` as its resource.
+Let's create an API for the book club, named `Book Club`, with `/club` as its
HTTP URL base path and `books` as its resource and `{isbn}` as a path parameter
used to identify a specific book by its ISBN.
+
+When using path parameters, the API must be defined with a response type of
`http`, and the path, including the actual path parameter value(s), will be
available in the `__ow_path` field of the action's JSON parameter.
```
-wsk api create -n "Book Club" /club /books get getBooks --response-type http
-wsk api create /club /books post postBooks --response-type http
-wsk api create /club /books put putBooks --response-type http
-wsk api create /club /books delete deleteBooks --response-type http
+wsk api create -n "Book Club" /club /books/{isbn} get getBooks --response-type
http
+wsk api create /club /books get getBooks --response-type
http
+wsk api create /club /books post postBooks --response-type
http
+wsk api create /club /books/{isbn} put putBooks --response-type
http
+wsk api create /club /books/{isbn} delete deleteBooks --response-type
http
```
Notice that the first action exposed with base path `/club` gets the API label
with name `Book Club` any other actions exposed under `/club` will be
associated with `Book Club`
Let's list all the actions that we just exposed.
```
-wsk api list -f
+wsk api list /club -f
```
```
ok: APIs
+Action: getBooks
+ API Name: Book Club
+ Base path: /club
+ Path: /books/{isbn}
+ Verb: get
+ URL: https://${APIHOST}:9001/api/${GENERATED_API_ID}/club/books/{isbn}
Action: getBooks
API Name: Book Club
Base path: /club
Path: /books
Verb: get
- URL: https://${APIHOST}:9001/api/21ef035/club/books
+ URL: https://${APIHOST}:9001/api/${GENERATED_API_ID}/club/books
Action: postBooks
API Name: Book Club
Base path: /club
Path: /books
Verb: post
- URL: https://${APIHOST}:9001/api/21ef035/club/books
+ URL: https://${APIHOST}:9001/api/${GENERATED_API_ID}/club/books
Action: putBooks
API Name: Book Club
Base path: /club
- Path: /books
+ Path: /books/{isbn}
Verb: put
- URL: https://${APIHOST}:9001/api/21ef035/club/books
+ URL: https://${APIHOST}:9001/api/${GENERATED_API_ID}/club/books/{isbn}
Action: deleteBooks
API Name: Book Club
Base path: /club
- Path: /books
+ Path: /books/{isbn}
Verb: delete
- URL: https://${APIHOST}:9001/api/21ef035/club/books
+ URL: https://${APIHOST}:9001/api/${GENERATED_API_ID}/club/books/{isbn}
```
Now just for fun let's add a new book `JavaScript: The Good Parts` with a HTTP
__POST__
```
-curl -X POST -d '{"name":"JavaScript: The Good Parts",
"isbn":"978-0596517748"}' https://${APIHOST}:9001/api/21ef035/club/books
+curl -X POST -d '{"name":"JavaScript: The Good Parts",
"isbn":"978-0596517748"}' -H "Content-Type: application/json"
https://${APIHOST}:9001/api/${GENERATED_API_ID}/club/books
Review comment:
For creating a new book use path parameter, I think that's the value add of
using path param
```
curl -X POST -d '{"name":"JavaScript: The Good Parts"}' -H "Content-Type:
application/json"
"https://${APIHOST}:9001/api/${GENERATED_API_ID}/club/books/978-0596517748";
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
