Normalize routes to remove "_" namespace and move fully qualified name to the end of the URI

[theophoric]

Currently the route to retrieve a list of actions associated with a given namespace and package is /namespaces/{namespaceName}/actions/{packageName}/. This is confusingly similar to the route for retrieving an action /namespaces/{namespaceName}/actions/{actionName}. I propose that the route for getting a list of actions associated with a package be changed to /namespaces/{namespaceName}/packages/{packageName}/actions to avoid this confusion and adhere more strictly to restful principles.

[theophoric]

As a corollary to this creating an action in the context of a package could be done through [POST] /namespaces/{namespaceName}/packages/{packageName}/actions

[rabbah]

Actions that are not in an explicitly named package are considered part of the default package. In this way, we can consider unifying the packages and actions API endpoints in this way /namespaces/{namespaceName}/packages/{packageName}/actions/{actionName} and reserve the package name default. In fact, we can take this further and eschew the packages endpoints all together, unifying the entity types in the same way.

[ioana-blue]

I'm in favor of this proposal since it follows the hierarchical nature of namespaces, packages and actions.

[sjfink]

I think this will be addressed in the v2 API changes.

[rabbah]

With the roll out of a stricter 1-1 mapping from key to namespace, an alternate way to evolve the API is to drop the namespace entirely from the URI (since the value will always be unambiguous and the _ place holder becomes canonical).

So rather than always specifying resources with /namespaces/_/{actions, triggers, rules, activations, packages}/name it becomes more convenient, elegant and uniform to drop the /namespaces/_ segment and treat the entire path following one of the collection qualifiers as the fully qualified name (where one segment implies resource in default namespace and package, two segments implies resource in default namespace with named package and entity) and three segments implies a fully qualified name with namespace, package and entity names.

This makes it potentially nicer to also filter activations in a namespace, package or by action: /activations/ lists all activation in the namespace, /activations/package-name for activations filtered by package, and /activations/package-name/entity-name for activations of an entity in a package. And of course /activations/namespace-name/package-name and /activations/namespace-name/package-name/action-name for activation in some other namespace and package assuming entitled subject.

(Alternatively, activations could be come their own resources under the actions collection actions/action-name/activations e.g.)

Related to #1635.

[rabbah]

While we can do this as part of v2 API, it's also possible to do as part of the current version with some nginx rewriting. Below I listed what the new API paths would look like for our current core API.

• Let ns = namespace name or “_”
• Let pkg = package name or “default”
• Let action = action name

basic CRUD + activate operations for actions, triggers, rules

show below for actions but intended to be the same for triggers and rules:

read get /api/v2/actions/ns/pkg/action

create/update put /api/v2/actions/ns/pkg/action

delete del /api/v2/actions/ns/pkg/action

activate post /api/v2/actions/ns/pkg/action

list all actions in package get /api/v2/actions/ns/pkg

list all actions in all packages in namespace get /api/v2/actions/ns

questions and considerations

• get/put/del only exec "code" or "zip"?
• want streaming for the “code” or “zip”, treat as attachments, subresource
• support ?override, ?createonly, ?updateonly for put
• list all actions in package can include bindings
• list all actions in all packages cannot easily includes bindings
• allow for action extensions for content type and projection for result path as in pr #1715?

basic CRUD operations for packages

get package or binding get /api/v2/packages/ns/pkg (default not allowed)

create/update package or binding put /api/v2/actions/ns/pkg (default not allowed, cannot be bound)

delete package or binding /api/v2/actions/ns/pkg (default not allowed)

list all packages and bindings in namespace fet /api/v2/actions/ns

basic read operations for activations

get by id /api/v2/activations/?id=

get by name /api/v2/activations/?name=

get all activations for action get /api/v2/activations/ns/pkg/action

list all activations for actions in package get /api/v2/activations/ns/pkg

list all activations in all packages in namespace get /api/v2/activations/ns

questions and considerations

• get only logs, as rubresource?
• get only results, as subresource?
• want streaming for the “logs” and the “results”, treat as attachments also
• support start, end, skip, limit on all list operations, return totals to allow pagination
• listing activations for packages may not include bindings

[michaelmarth]

show below for actions but intended to be the same for triggers and rules:

Would this also include compositions like sequences?

[rabbah]

Would this also include compositions like sequences?

a sequence is an action - so yes.

[michaelmarth]

ack. so the the "keyword" to address compositions would be "action" as well? e.g.

put /api/v2/actions/ns/pkg/action

would also be used to a composition/sequence?

[rabbah]

That's correct - this is an important property for actions in openwhisk (a composition produces an action).

[dubee]

@rabbah, namespace or no namespace in API V2?

[rabbah]

do you mean should we continue to allow "_" for convenience? I don't see how we can eliminate namespace (in case one is referring to a public package for example).