Discussion api2 admin vs. invoke/fire

[csantanapr]

When we start work on api v2 I want to propose that we stop using POST on the action or trigger resource to invoke or fire

This will allow for clients to do admin tasks with CRUD on the resources. Were a POST to an action resource will create the action, and a PUT will update an existing action.

we can have a base url path to be use for differentiate, This could potentially have a set of controllers that deal with admin tasks and another set that deals with high performances tasks (i.e. invoke/fire)

This URLS will support CRUD to manage the resources (create (POST), read(GET), update(PUT), delete(DELETE))

• https://{BASE URL}/api/v2/namespaces/{namespace}/actions/[{packageName}/]{actionName}
• https://{BASE URL}/api/v2/namespaces/{namespace}/triggers/{triggerName}

Have alternative APIs for invoke and trigger, have invoke or trigger in the path Maybe at the start:

• https://{BASE URL}/api/v2/invoke/namespaces/{namespace}/actions/[{packageName}/]{actionName}
• https://{BASE URL}/api/v2/fire/namespaces/{namespace}/triggers/{triggerName}

cc @rabbah

[rabbah]

A put is commonly used for create or update. There is perhaps a great debate about put vs post to create. But when you put you specify the resource you're creating/updating and that is different from a post where you customarily do unsafe/non-idempotent operations.

http://www.ietf.org/rfc/rfc2616.txt section 9.6

   The PUT method requests that the enclosed entity be stored under the
   supplied Request-URI. If the Request-URI refers to an already
   existing resource, the enclosed entity SHOULD be considered as a
   modified version of the one residing on the origin server.

and later

   The fundamental difference between the POST and PUT requests is
   reflected in the different meaning of the Request-URI. The URI in a
   POST request identifies the resource that will handle the enclosed
   entity.

So using a POST to create should mean moving the name of the entity (action) to the POST body and not the URI.

[csantanapr]

OK so your saying that you agree with me that having a POST to create an action is good thing?

So your saying we go with something like this?: GET, PUT, DELETE on this URIs https://{BASE URL}/api/v2/namespaces/{namespace}/actions/[{packageName}/]{actionName} https://{BASE URL}/api/v2/namespaces/{namespace}/triggers/{triggerName}

POST on this URIs https://{BASE URL}/api/v2/namespaces/{namespace}/actions body will have action entity to create including packagename it belongs to https://{BASE URL}/api/v2/namespaces/{namespace}/triggers body will have trigger entity to create

[rabbah]

OK so your saying that you agree with me that having a POST to create an action is good thing?

I neither agreed or disagreed. I am pointing out that what you proposed is not consistent wrt the verbs.

I prefer the use of the verbs we have now - modulo fixing the packages inconsistency in the URI.

I also find the use of fire and invoke early in the URI path to be inconsistent with REST principles vs. suggestting a POST to an activations resource at the end of the URI e.g., POST /api/v2/namespaces/ns/actions/a/activations.

[csantanapr]

Yeah I like the idea about a POST to /api/v2/namespaces/ns/actions/a/activations That would work for any type of activations? triggers and actions?

In reality that's what's happening, the POST will cause the creation of an invocation, and like we discuss in the past I think an activation should be recorded in the DB as early as possible, this way any subsequent calls to get the activation by ID will get a valid response.

Are there any early designs for v2 and does it covers things we are discussing in this issue?

[rabbah]

Nothing formal yet. There's a write up that I have on unifying activations API that I should post here. Otherwise check the v2 epic (there's one on normalizing the packages in the URI).

[csantanapr]

Was not able to find such v2 epic on this open repo.

Is there any thoughts on having some sort of namespace for a "project" for grouping together rules, triggers, actions, not just on namespace like we have today but have multiple projects for each able to group things. Maybe this is some of tags and filters.

[rabbah]

@csantanapr added this issue/discussion to the above referenced epic.

[csantanapr]

thanks @rabbah

[rabbah]

@csantanapr if you want to weigh in on the v2 API let's consolidate here: https://github.com/openwhisk/openwhisk/issues/219#issuecomment-272951007.