REST API: Schemas in Add- und Edit-Szenarien verfügbar machen

[lukasgraf]

In plone.restapi ist neu eine Implementierung für einen @sources endpoint vorhanden, aber diese kann erst für Edit-Formulate gebraucht werden, noch nicht für Add.

Der Grund dafür ist, dass der @sources endpoint auf einem Kontext aufgerufen werden muss, und die Source über den Namen des Feldes adressiert werden muss:

GET (context)/@sources/(field_name)

Dieser Aufruf funktioniert aber nur, wenn das Objekt bereits existiert, für welches die Source abgefragt werden soll.

Für Add-Formulare muss die Source stattdessen den container als Kontext erhalten, und das Schema kann nicht vom Kontext bestimmt werden (da er noch nicht existiert), sondern muss über einen vom Benutzer anzugebenden Typ nachgeschaut werden.

Für ein Add-Szenario würde ich daher folgenden Aufruf vorschlagen:

GET (container)/@sources/(portal_type)/(field_name)

Für ein Add-Formular würde der @sources endpoint also auf dem container aufgerufen, zu welchem das neue Objekt hinzugefügt werden soll. Zusätzlich muss mit dem zweiten Pfad-Parameter portal_type angegeben werden, welcher Typ erstellt werden soll.

Aufgrund des portal_types wird der endpoint dann die FTI, und das Schema des Typs nachschlagen, mittels dem Angegebenen field_name das Feld bestimmen, und die Source des Feldes im Kontext des containers rendern.

---

Der @types endpoint müsste in einem ähnlichen Stil angepasst werden:
Die Vocabulary-URLs in den vom @types endpoint zurückgegeben Schemas müssten so angepasst werden, dass sie je nach Aufruf-Art des @types endpoints auf Vocabularies/Sources für add forms oder edit forms verlinken.

Leider ist aber der Aufruf des @types endpoints ohne parameter auf einem Kontext schon belegt mit Funktionalität, welche überhaupt nichts mit Schemas zu tun hat: context/@types ohne weitere Argumente liefert die Liste der verfügbaren Typen zurück, mit der Information ob sie addable sind. Diesen Aspekt des Endpoints darauf zu Ändern, das Edit-Schema für den entsprechenden Kontext zurückzugeben, wäre ein Breaking change.

Ich würde daher vorschlagen, einen neuen Endpoint @schema einzuführen, der ausschliesslich Schemas ausliefert:

Intent: Edit

GET (context)/@schema

Intent: Add

GET (container)/@schema/(portal_type)

Auch hier würde also implizit, durch Vorhandensein oder Abwesenheit des portal_type Parameters, bestimmt ob es sich um ein add oder edit-Szenario (Intent) handelt. Der @schema endpoint würde in den URLs für die Vocabularies/Sourcen diesen Intent erhalten, indem er den portal_type Parameter an die enstprechenden endpoints weitergibt (dazu müssen diese den natürlich unterstützen, und sich analog verhalten).

[lukasgraf]

We propose the following:

New alternative invocation syntax for vocabulary-like endpoints

The Vocabulary-like endpoints (@sources, @querysources and @vocabularies) shall be extended to support an alternative Syntax to accept a portal_type Parameter.

When this parameter is supplied, they should assume add intent, and treat the context they're invoked on as a container where a new object of the given type will be created.

Their existing invocation syntax would imply edit intent.

For the new invocation syntax to signal add intent, we propose that these endpoints accept an additional positional path parameter.

• If invoked with two parameters, the parameters are /(portal_type)/(name)
• If invoked with one parameter, the parameter is /(name)
  (this is the invocation syntax that already exists)

(Where name is either a vocabulary name (in the case of @vocabularies) or a field name (@sources and @querysources).

These endpoints would therefore have the following invocation styles and corresponding intents:

Edit (existing syntax)

Add (new, additional syntax)

---

Edit (existing)

Add (new)

---

Edit (existing)

Add (new)

Or, as more concrete examples when requesting the vocab or source for a field on a document that is either to be created in a folder (add) or already exists (edit):

edit: /Plone/my-folder/doc1/@sources/allow_discussion
add:  /Plone/my-folder/@sources/Document/allow_discussion

edit: /Plone/my-folder/doc1/@querysources/allow_discussion
add:  /Plone/my-folder/@querysources/Document/allow_discussion

edit: /Plone/my-folder/doc1/@vocabularies/plone.app.vocabularies.Keywords
add:  /Plone/my-folder/@vocabularies/Document/plone.app.vocabularies.Keywods

---

New @schema endpoint

Once these endpoint support an invocation style that unambiguously signals intent, the same pattern could be applied to the @types endpoint, so that it wires up the correct URLs in the schema it returns depending on how it was invoked.

However, invoking @types without parameters on a context is already implemented as listing existing types and whether they're addable or not. We therefore propose to introduce a new @schema that only returns a schema, and can be invoked in the two different ways described above:

Edit

Add

Example:

edit: /Plone/my-folder/doc1/@schema
add:  /Plone/my-folder/@schema/Document

In terms of implementation, the @schema endpoint would use the same implementation as @types/(portal_type), which just would be updated to produce intent-dependent vocab URLs.

Deprecate retrieving schemas from @types

The @types endpoint currently serves a dual purpose, and IMHO that's part of the problem. Once the new @schema endpoint is introduced

• we should issue deprecation warnings on @types/(portal_type) requests
• describe that aspect of the @types endpoint as deprecated
• link to the new @schema endpoint (add intent) from the @types response of existing/addable types (this can be considered a non-breaking change IMHO - hypertext aware clients that just follow URLs shouldn't notice a difference)

[phgross]

Abwarten der Anpassung im og.core und evtl. Diskussion in p.a.restapi.