openwhisk-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mrutkow...@apache.org
Subject [incubator-openwhisk-wskdeploy] branch master updated: #825 Added documentation and example for API Gateway hello world (#829)
Date Wed, 28 Mar 2018 18:57:08 GMT
This is an automated email from the ASF dual-hosted git repository.

mrutkowski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk-wskdeploy.git


The following commit(s) were added to refs/heads/master by this push:
     new 0e3ce8a  #825 Added documentation and example for API Gateway hello world (#829)
0e3ce8a is described below

commit 0e3ce8ae73e0342093111c488d08c0606dc823f8
Author: Bruno Girin <brunogirin@gmail.com>
AuthorDate: Wed Mar 28 19:57:03 2018 +0100

    #825 Added documentation and example for API Gateway hello world (#829)
---
 docs/examples/manifest_hello_world_apigateway.yaml |  30 ++++++
 docs/examples/wskdeploy_apigateway_helloworld.md   | 118 +++++++++++++++++++++
 docs/programming_guide.md                          |   2 +
 docs/wskdeploy_triggerrule_trigger_bindings.md     |   2 +-
 4 files changed, 151 insertions(+), 1 deletion(-)

diff --git a/docs/examples/manifest_hello_world_apigateway.yaml b/docs/examples/manifest_hello_world_apigateway.yaml
new file mode 100644
index 0000000..208a6e0
--- /dev/null
+++ b/docs/examples/manifest_hello_world_apigateway.yaml
@@ -0,0 +1,30 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for additional
+# information regarding copyright ownership.  The ASF licenses this file to you
+# under the Apache License, Version 2.0 (the # "License"); you may not use this
+# file except in compliance with the License.  You may obtain a copy of the License
+# at:
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations under the License.
+#
+
+# Example: Basic Hello World action with API
+packages:
+  hello_world_package:
+    version: 1.0
+    license: Apache-2.0
+    actions:
+      hello_world:
+        function: src/hello.js
+        web-export: true
+    apis:
+      hello-world:
+        hello:
+          world:
+            hello_world: GET
diff --git a/docs/examples/wskdeploy_apigateway_helloworld.md b/docs/examples/wskdeploy_apigateway_helloworld.md
new file mode 100644
index 0000000..570e08d
--- /dev/null
+++ b/docs/examples/wskdeploy_apigateway_helloworld.md
@@ -0,0 +1,118 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for additional
+# information regarding copyright ownership.  The ASF licenses this file to you
+# under the Apache License, Version 2.0 (the # "License"); you may not use this
+# file except in compliance with the License.  You may obtain a copy of the License
+# at:
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations under the License.
+#
+-->
+
+# API Gateway
+
+## The "Hello World" API
+
+This example builds on the ["Hello World" Action](wskdeploy_action_helloworld.md#actions)
example by adding an API definition on top of that action so that I can be queried via an
HTTP call.
+
+It shows how to:
+- update the Action named ‘hello_world’ to expose it to the gateway.
+- specify the API's endpoint that will trigger the action.
+
+### Manifest file
+#### _Example: “Hello world” action with API_
+```yaml
+packages:
+  hello_world_package:
+    version: 1.0
+    license: Apache-2.0
+    actions:
+      hello_world:
+        function: src/hello.js
+        web-export: true
+    apis:
+      hello-world:
+        hello:
+          world:
+            hello_world: GET
+```
+
+There are two key changes to this file:
+- the `hello_world` action now has the `web-export` flag set to `true`.
+- a new `apis` block has been created.
+
+The `apis` block contains a number of groups of API endpoint. Each endpoint is then defined
by the hierarchy. In this case, we are creating the `hello/world` endpoint. The leaf in the
structure specifies the action to trigger when the given HTTP verb is sent to that endpoint,
in this case, when the HTTP verb `GET` is used on the `hello/world` endpoint, trigger the
`hello_world` action.
+
+### Deploying
+
+You can actually deploy the "hello world API gateway" manifest from the incubator-openwhisk-wskdeploy
project directory if you have downloaded it from GitHub:
+
+```sh
+$ wskdeploy -m docs/examples/manifest_hello_world_apigateway.yaml
+```
+
+### Invoking
+
+Check the full URL of your API first:
+```sh
+$ wsk api list
+```
+
+This will return some information on the API, including the full URL, which
+should end with `hello/world`. It can then be invoked:
+
+```sh
+$ curl <url>
+```
+
+### Result
+The invocation should return a JSON response that includes this result:
+
+```json
+{
+    "greeting": "Hello, undefined from undefined"
+}
+```
+
+The output parameter '```greeting```' contains "_undefined_" values for the '```name```'
and '```place```' input parameters as they were not provided in the manifest or the HTTP call.
You can provide them as query parameters:
+
+```sh
+$ curl <url>?name=World&place=Earth
+```
+
+### Discussion
+
+This "hello world" example represents the minimum valid Manifest file which includes only
the required parts of the Package, Action and API descriptors.
+
+### Source code
+The source code for the manifest and JavaScript files can be found here:
+- [manifest_hello_world_apigateway.yaml](examples/manifest_hello_world_apigateway.yaml)
+- [hello.js](examples/src/hello.js)
+
+### Specification
+For convenience, the Packages and Actions grammar can be found here:
+- **[Packages](../specification/html/spec_packages.md#packages)**
+- **[Actions](../specification/html/spec_actions.md#actions)**
+
+---
+<!--
+ Bottom Navigation
+-->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a href="wskdeploy_triggerrule_trigger_bindings.md#triggers-and-rules">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
+    <!--<td><a href="">next&nbsp;&gt;&gt;</a></td>-->
+  </tr>
+</table>
+</div>
+</html>
diff --git a/docs/programming_guide.md b/docs/programming_guide.md
index 1c92b92..ed56256 100644
--- a/docs/programming_guide.md
+++ b/docs/programming_guide.md
@@ -54,6 +54,8 @@ Each example shows the "code", that is the Package Manifest, Deployment
file and
 - Trigger and Rule examples
   - [Basic Trigger and Rule](wskdeploy_triggerrule_basic.md#triggers-and-rules) - adding
a basic trigger and rule to the advanced Parameter "hello world".
   - [Binding parameters in a Deployment file](wskdeploy_triggerrule_trigger_bindings.md#triggers-and-rules)
- using a deployment file to bind values to a Trigger’s parameters and applying them to
a compatible manifest file.
+- API Gateway examples
+  - [The "Hello World" API Gateway](wskdeploy_apigateway_helloworld.md#api-gateway) - deploy
a "hello world" JavaScript function with associated HTTP API.
 
 ---
 <!--
diff --git a/docs/wskdeploy_triggerrule_trigger_bindings.md b/docs/wskdeploy_triggerrule_trigger_bindings.md
index 39eba09..ab51cce 100644
--- a/docs/wskdeploy_triggerrule_trigger_bindings.md
+++ b/docs/wskdeploy_triggerrule_trigger_bindings.md
@@ -130,7 +130,7 @@ For convenience, the Actions and Parameters grammar can be found here:
   <tr>
     <td><a href="wskdeploy_triggerrule_basic.md#triggers-and-rules">&lt;&lt;&nbsp;previous</a></td>
     <td><a href="programming_guide.md#guided-examples">Example Index</a></td>
-<!--    <td><a href="">next&nbsp;&gt;&gt;</a></td>
-->
+    <td><a href="wskdeploy_apigateway_helloworld.md#packages">next&nbsp;&gt;&gt;</a></td>
   </tr>
 </table>
 </div>

-- 
To stop receiving notification emails like this one, please contact
mrutkowski@apache.org.

Mime
View raw message