[deepamehta-devel] Creating composite topics via REST API

Jörg Richter jri at deepamehta.de
Fri Sep 30 16:49:37 CEST 2016


Hi Robert,

On 19 Sep 2016, at 21:07, Robert Schuster <robert.schuster.rs01 at gmail.com> wrote:

> However after discussion my approach in general I think I am going to use core's REST API from JavaScript directly. The reason is that I would otherwise spend a lot of time writing boilerplate serialization/deserialization code.

Yes, that's a good idea :-)

In DM creating/updating composite topic structures is a complex matter, unfortunately not well documented at the moment. Starting with this posting I'll try to decompose it in smaller units.

Let's start with creating a topic of type Person (as defined in the DM standard distribution), and, as a start, only focusing on the Name and Birthday "properties" (rather called "Child Topics" in DM) as these already require crucial explanations. To explain the REST API in a tool agnostic fashion I'll use curl syntax in the examples.

To create a Person topic:

curl -H Cookie:JSESSIONID=nv23xiaj5n751et10ga74d1u -H Cookie:dm4_workspace_id=2954 -H Content-Type:application/json -X POST localhost:8080/core/topic -d '{
    "type_uri": "dm4.contacts.person",
    "childs": {
        "dm4.contacts.person_name": {
            "dm4.contacts.first_name": "Karl",
            "dm4.contacts.last_name": "Schmidt"
        },
        "dm4.datetime.date#dm4.contacts.date_of_birth": {
            "dm4.datetime.day": "ref_id:584",
            "dm4.datetime.month": "ref_id:491",
            "dm4.datetime.year": 1970
        }
    }
}'

In the JSESSIONID cookie you must pass a valid session ID. Without a session you're not able to create/edit/delete any content. To obtain a session ID login via the "/accesscontrol" service.

In the dm4_workspace_id cookie you must pass a workspace ID. DM will assign all things created to that workspace then. To obtain a workspace ID use the "/workspaces" service.

Set the Content-Type header to "application/json" as you pass JSON data in the request body. Without that header you'll get a 415 (Unsupported Media Type) response.

To create a new topic POST to the "/core/topic" resource and pass the topic data in the request body as a JSON object. The "type_uri" property is mandatory and specifies the topic's type. The (JSON) value format must correspond to the type definition, e.g. "Karl" is formatted as "Text"  while 1970 is formatted as "Number" (that is without double quotes).

In case of a composite type you can pass the child topics in the "childs" property, another JSON object. That object's nesting structure corresponds to the type definition's composite structure (see screenshot).

If an association definition (that is at type-level) is qualified with a "Custom Association Type" in your JSON the child type URI must be qualified as well, using the "#" character. Lets look at this example:

	"dm4.datetime.date#dm4.contacts.date_of_birth"

Here "dm4.datetime.date" is the URI of the Date child topic type, and "dm4.contacts.date_of_birth" is the URI of the association type that is defined as the "Custom Association Type".



Note, that at instance-level (right hand side in the screenshot) the association between "Karl Schmidt" and "12 31 1970" is of type "Data of Birth" then.

If at type-level an association definition is defined as "Aggregation Definition" (in contrast to "Composition Definition"), then at instance-level you have to decide wether to *create* a new child topic, or *reference* an existing one. To reference an existing one, you must state its topic ID, preceded by the "ref_id:" prefix. Let's look at this example:

	"dm4.datetime.month": "ref_id:491"

Here 491 is the ID of the "December" topic (that is an instance of type "Month").

If you don't use the "ref_id:" prefix a new instance will be created, as in:

	"dm4.datetime.year": 1970

Here a new "Year" topic instance "1970" will be created, regardless if such an instance exists already.

General hint: in a type definition "Aggregation Definition" (dark green lines in the screenshot) is used to express that the child instances are meant to be *shared* between several parent instances. E.g. the very same "December" topic is meant to be shared by all the "Date" instances. In the DB there might be hundreds of "Date" instances, but only 12 Month instances.

To query the IDs of existing e.g. "Year" instances you can use the "GET /core/topic/by_type/<uri>" request. In a create/update form your frontend could offer all existing instances by the means of a combo box. This way your frontend can find out if the user selected an existing instance or is about to create a new one, in order to decide wether to include the "ref_id:" prefix in the request or not. (The DM Webclient works this way.)

In one of my next postings I'll talk about *updating* composite topics.

> Regarding that API: Is there an online documentation for the REST API or should I simply consult the respective service class and read the API from the Annotations?

See chapter 6 "Development" in the documentation:
	https://trac.deepamehta.de/wiki/Documentation
In particular:
	https://trac.deepamehta.de/wiki/DataFormat
	https://trac.deepamehta.de/wiki/RestApi
Be aware that some particularities might be outdated on these pages.
Feel free register at the Trac and update these pages :-)

The definitive source to learn the DM Core REST API is investigating the JAX-RS annotations in WebservicePlugin.java (part of module dm4-webservice). To learn the other DM standard services (e.g. AccessControlService or WorkspaceService) see the ...Plugin.java main file of the respective modules.

Cheers,
Jörg

-------------- n�chster Teil --------------
Ein Dateianhang mit HTML-Daten wurde abgetrennt...
URL: <http://lists.deepamehta.de/pipermail/devel-lists.deepamehta.de/attachments/20160930/4a966853/attachment.html>
-------------- n�chster Teil --------------
Ein Dateianhang mit Bin�rdaten wurde abgetrennt...
Dateiname   : PastedGraphic-2.png
Dateityp    : image/png
Dateigr��e  : 81464 bytes
Beschreibung: nicht verf�gbar
URL         : <http://lists.deepamehta.de/pipermail/devel-lists.deepamehta.de/attachments/20160930/4a966853/attachment.png>
-------------- n�chster Teil --------------
Ein Dateianhang mit Bin�rdaten wurde abgetrennt...
Dateiname   : signature.asc
Dateityp    : application/pgp-signature
Dateigr��e  : 496 bytes
Beschreibung: Message signed with OpenPGP using GPGMail
URL         : <http://lists.deepamehta.de/pipermail/devel-lists.deepamehta.de/attachments/20160930/4a966853/attachment.sig>


More information about the devel mailing list