spec_apis.md

APIs

The API entity schema is used to define an OpenWhisk API within a manifest.

Fields

Key Name	Required	Value Type	Default	Description
method	yes	string	N/A	The HTTP method for the endpoint. All valid HTTP methods are supported, but a response type value of http may be required to correctly process the associated request.
response	no	string	http	The response type or content extension used when the API Gateway invokes the web action. See https://github.com/apache/openwhisk/blob/master/docs/webactions.md#content-extensions.

Grammar

<apiName>:
    <basePath>:
        <relativePath>:
            <actionName>:
                method: <get | delete | put | post | ...>
                response: <http | json | text | html>

Example

packages:
  hello_world_package:
    version: 1.0
    license: Apache-2.0
    actions:
      hello_world:
        function: src/hello.js
        annotations:
          web-export: true
    apis:
      hello-world:
        hello:
          world:
            hello_world:
              method: GET
              response: json
      goodbye-world:
        hello:
          world:
            hello_world:
              method: DELETE
              response: json

Requirements

• The API name MUST be less than or equal to 256 characters.
• The API basePath value MUST NOT start with a / character.
• The API relativePath value MUST NOT start with a / character.
• The API entity schema includes all required fields declared above.
• Only web actions, actions having web-export set to true, can be used as an API endpoint's action.
  • If needed, the action will be automatically converted to a web action during deployment.
• A valid API entity MUST have one or more valid endpoints defined.

Notes

• When an API endpoint is being added to an existing API, the apiName in the manifest is ignored.
• See https://github.com/apache/openwhisk/blob/master/docs/webactions.md for the complete set of supported response values, also known as content extensions.
• Using a response value of http will give you the most control over the API request and response handling.

---