[openwhisk] branch master updated: Remove docs related to projections. (#4592)

[ch...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

chetanm pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/openwhisk.git


The following commit(s) were added to refs/heads/master by this push:
     new d7c5c04  Remove docs related to projections. (#4592)
d7c5c04 is described below

commit d7c5c04ad052f9c6d27a943793bf8221ccf168cf
Author: rodric rabbah <ro...@gmail.com>
AuthorDate: Tue Aug 27 05:38:45 2019 -0400

    Remove docs related to projections. (#4592)
---
 docs/webactions.md | 51 +++++++++++++++++++++++----------------------------
 1 file changed, 23 insertions(+), 28 deletions(-)

diff --git a/docs/webactions.md b/docs/webactions.md
index 7cf74c1..83b297f 100644
--- a/docs/webactions.md
+++ b/docs/webactions.md
@@ -135,8 +135,8 @@ It is important to be aware of the [response size limit](reference.md) for actio
 An OpenWhisk action that is not a web action requires both authentication and must respond with a JSON object. In contrast, web actions may be invoked without authentication, and may be used to implement HTTP handlers that respond with _headers_, _statusCode_, and _body_ content of different types. The web action must still return a JSON object, but the OpenWhisk system (namely the `controller`) will treat a web action differently if its result includes one or more of the following as to [...]
 
 1. `headers`: a JSON object where the keys are header-names and the values are string, number, or boolean values for those headers (default is no headers). To send multiple values for a single header, the header's value should be a JSON array of values.
-2. `statusCode`: a valid HTTP status code (default is 200 OK if body is not empty otherwise 204 No Content).
-3. `body`: a string which is either plain text, JSON object or array, or a base64 encoded string for binary data (default is empty response).
+1. `statusCode`: a valid HTTP status code (default is 200 OK if body is not empty otherwise 204 No Content).
+1. `body`: a string which is either plain text, JSON object or array, or a base64 encoded string for binary data (default is empty response).
 
 The `body` is considered empty if it is `null`, the empty string `""` or undefined.
 
@@ -147,11 +147,11 @@ The controller will pass along the action-specified headers, if any, to the HTTP
 All web actions, when invoked, receives additional HTTP request details as parameters to the action input argument. They are:
 
 1. `__ow_method` (type: string): the HTTP method of the request.
-2. `__ow_headers` (type: map string to string): the request headers.
-3. `__ow_path` (type: string): the unmatched path of the request (matching stops after consuming the action extension).
-4. `__ow_user` (type: string): the namespace identifying the OpenWhisk authenticated subject.
-5. `__ow_body` (type: string): the request body entity, as a base64 encoded string when content is binary or JSON object/array, or plain string otherwise.
-6. `__ow_query` (type: string): the query parameters from the request as an unparsed string.
+1. `__ow_headers` (type: map string to string): the request headers.
+1. `__ow_path` (type: string): the unmatched path of the request (matching stops after consuming the action extension).
+1. `__ow_user` (type: string): the namespace identifying the OpenWhisk authenticated subject.
+1. `__ow_body` (type: string): the request body entity, as a base64 encoded string when content is binary or JSON object/array, or plain string otherwise.
+1. `__ow_query` (type: string): the query parameters from the request as an unparsed string.
 
 A request may not override any of the named `__ow_` parameters above; doing so will result in a failed request with status equal to 400 Bad Request.
 
@@ -162,12 +162,10 @@ The `__ow_user` is only present when the web action is [annotated to require aut
 Web actions bring some additional features that include:
 
 1. `Content extensions`: the request must specify its desired content type as one of `.json`, `.html`, `.http`, `.svg` or `.text`. This is done by adding an extension to the action name in the URI, so that an action `/guest/demo/hello` is referenced as `/guest/demo/hello.http` for example to receive an HTTP response back. For convenience, the `.http` extension is assumed when no extension is detected.
-2. `Projecting fields from the result`: When used with content extensions other than `.http`, the path that follows the action name is used to project out one or more levels of the response. For example, 
-`/guest/demo/hello.html/body`. This allows an action which returns a dictionary `{body: "..." }` to project the `body` property and directly return its string value instead. The projected path follows an absolute path model (as in XPath).
-3. `Query and body parameters as input`: the action receives query parameters as well as parameters in the request body. The precedence order for merging parameters is: package parameters, binding parameters, action parameters, query parameter, body parameters with each of these overriding any previous values in case of overlap . As an example `/guest/demo/hello.http?name=Jane` will pass the argument `{name: "Jane"}` to the action.
-4. `Form data`: in addition to the standard `application/json`, web actions may receive URL encoded from data `application/x-www-form-urlencoded data` as input.
-5. `Activation via multiple HTTP verbs`: a web action may be invoked via any of these HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`, as well as `HEAD` and `OPTIONS`.
-6. `Non JSON body and raw HTTP entity handling`: A web action may accept an HTTP request body other than a JSON object, and may elect to always receive such values as opaque values (plain text when not binary, or base64 encoded string otherwise).
+1. `Query and body parameters as input`: the action receives query parameters as well as parameters in the request body. The precedence order for merging parameters is: package parameters, binding parameters, action parameters, query parameter, body parameters with each of these overriding any previous values in case of overlap . As an example `/guest/demo/hello.http?name=Jane` will pass the argument `{name: "Jane"}` to the action.
+1. `Form data`: in addition to the standard `application/json`, web actions may receive URL encoded from data `application/x-www-form-urlencoded data` as input.
+1. `Activation via multiple HTTP verbs`: a web action may be invoked via any of these HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`, as well as `HEAD` and `OPTIONS`.
+1. `Non JSON body and raw HTTP entity handling`: A web action may accept an HTTP request body other than a JSON object, and may elect to always receive such values as opaque values (plain text when not binary, or base64 encoded string otherwise).
 
 The example below briefly sketches how you might use these features in a web action. Consider an action `/guest/demo/hello` with the following body:
 ```javascript
@@ -176,8 +174,7 @@ function main(params) {
 }
 ```
 
-When this action is invoked as a web action, you can alter the response of the web action by projecting different paths from the result.
-For example, to return the entire object, and see what arguments the action receives:
+This is an example of invoking the web action using the `.json` extension, indicating a JSON response.
 
 ```bash
 $ curl https://${APIHOST}/api/v1/web/guest/demo/hello.json
@@ -195,7 +192,8 @@ $ curl https://${APIHOST}/api/v1/web/guest/demo/hello.json
 }
 ```
 
-and with a query parameter:
+You can supply query parameters.
+
 ```bash
 $ curl https://${APIHOST}/api/v1/web/guest/demo/hello.json?name=Jane
 {
@@ -213,7 +211,8 @@ $ curl https://${APIHOST}/api/v1/web/guest/demo/hello.json?name=Jane
 }
 ```
 
-or form data:
+You may use form data as input.
+
 ```bash
 $ curl https://${APIHOST}/api/v1/web/guest/demo/hello.json -d "name":"Jane"
 {
@@ -233,7 +232,8 @@ $ curl https://${APIHOST}/api/v1/web/guest/demo/hello.json -d "name":"Jane"
 }
 ```
 
-or JSON object:
+You may also invoke the action with a JSON object.
+
 ```bash
 $ curl https://${APIHOST}/api/v1/web/guest/demo/hello.json -H 'Content-Type: application/json' -d '{"name":"Jane"}'
 {
@@ -253,15 +253,10 @@ $ curl https://${APIHOST}/api/v1/web/guest/demo/hello.json -H 'Content-Type: app
 }
 ```
 
-and to project just the name (as text):
-```bash
-$ curl https://${APIHOST}/api/v1/web/guest/demo/hello.text/response/name?name=Jane
-Jane
-```
+You see above that for convenience, query parameters, form data, and JSON object body entities are all treated as dictionaries, and their values are directly accessible as action input properties. This is not the case for web actions which opt to instead handle HTTP request entities more directly, or when the web action receives an entity that is not a JSON object.
 
-You see above that for convenience, query parameters, form data, and JSON object body entities are all treated as dictionaries are their values are directly accessible as action input properties. This is not the case for web actions which opt to instead handle HTTP request entities more directly, or when the web action receives an entity that is not a JSON object.
+Here is an example of using a "text" content-type with the same example shown above.
 
-Here is an example of using a "text" content-type with the same example shown above:
 ```bash
 $ curl https://${APIHOST}/api/v1/web/guest/demo/hello.json -H 'Content-Type: text/plain' -d "Jane"
 {
@@ -284,7 +279,7 @@ $ curl https://${APIHOST}/api/v1/web/guest/demo/hello.json -H 'Content-Type: tex
 
 ## Content extensions
 
-A content extension is generally required when invoking a web action; the absence of an extension assumes `.http` as the default. The `.json` extension does not require a projection path, and the `.http` extension does not support a projection path. However, `.html`, `.svg` and `.text` extensions require a projection path. For convenience, the default path is assumed to match the extension name. So to invoke a web action and receive an `.html` response, the action must respond with a JSO [...]
+A content extension is generally required when invoking a web action; the absence of an extension assumes `.http` as the default. The fully qualified name of the action must include its package name, which is `default` if the action is not in a named package.
 
 
 ## Protected parameters
@@ -500,8 +495,8 @@ Action parameters are inherited from its package, and the binding if there is on
 
 When an OpenWhisk action fails, there are two different failure modes. The first is known as an _application error_ and is analogous to a caught exception: the action returns a JSON object containing a top level `error` property. The second is a _developer error_ which occurs when the action fails catastrophically and does not produce a response (this is similar to an uncaught exception). For web actions, the controller handles application errors as follows:
 
-1. Any specified path projection is ignored and the controller projects the `error` property instead.
-2. The controller applies the content handling implied by the action extension to the value of the `error` property.
+1. The controller projects an `error` property from the response object.
+1. The controller applies the content handling implied by the action extension to the value of the `error` property.
 
 Developers should be aware of how web actions might be used and generate error responses accordingly. For example, a web action that is used with the `.http` extension
 should return an HTTP response, for example: `{error: { statusCode: 400 }`. Failing to do so will in a mismatch between the implied content-type from the extension and the action content-type in the error response. Special consideration must be given to web actions that are sequences, so that components that make up a sequence can generate adequate errors when necessary.