mdeuser 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_r170916708
########## 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: @csantanapr it's my understanding that rest apis for creating resources do not typically specify the entity identifier on the path. instead that's either in the payload or returned in the response. https://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/ ---------------------------------------------------------------- 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