<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div class=""><br class=""></div><div class="">Hi Robert,<br class=""><br class=""></div><div class="">On 19 Sep 2016, at 21:07, Robert Schuster <<a href="mailto:robert.schuster.rs01@gmail.com" class="">robert.schuster.rs01@gmail.com</a>> wrote:<br class=""><br class=""><blockquote type="cite" class="">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.<br class=""></blockquote><br class=""></div><div class="">Yes, that's a good idea :-)</div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">To create a Person topic:</div><div class=""><br class=""></div><div class="">curl -H Cookie:JSESSIONID=nv23xiaj5n751et10ga74d1u -H Cookie:dm4_workspace_id=2954 -H Content-Type:application/json -X POST localhost:8080/core/topic -d '{<br class=""> "type_uri": "dm4.contacts.person",<br class=""> "childs": {<br class=""> "dm4.contacts.person_name": {<br class=""> "dm4.contacts.first_name": "Karl",<br class=""> "dm4.contacts.last_name": "Schmidt"<br class=""> },<br class=""> "dm4.datetime.date#dm4.contacts.date_of_birth": {<br class=""> "dm4.datetime.day": "ref_id:584",<br class=""> "dm4.datetime.month": "ref_id:491",<br class=""> "dm4.datetime.year": 1970<br class=""> }<br class=""> }<br class="">}'<br class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">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).</div><div class=""><br class=""></div><div class="">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).</div><div class=""><br class=""></div><div class="">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:</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span>"dm4.datetime.date#dm4.contacts.date_of_birth"</div><div class=""><br class=""></div><div class="">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".</div><div class=""><br class=""></div><div class=""><img apple-inline="yes" id="F9377EEB-EE72-4A04-9483-6EAE499BF658" height="330" width="640" apple-width="yes" apple-height="yes" src="cid:E4F6CA2E-F604-439E-A133-E93B96B373BA@localdomain" class=""></div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">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:</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span>"dm4.datetime.month": "ref_id:491"</div><div class=""><br class=""></div><div class="">Here 491 is the ID of the "December" topic (that is an instance of type "Month").</div><div class=""><br class=""></div><div class="">If you don't use the "ref_id:" prefix a new instance will be created, as in:</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span>"dm4.datetime.year": 1970</div><div class=""><br class=""></div><div class="">Here a new "Year" topic instance "1970" will be created, regardless if such an instance exists already.</div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">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.)</div><div class=""><br class=""></div><div class="">In one of my next postings I'll talk about *updating* composite topics.</div><div class=""><br class=""></div><div class=""><blockquote type="cite" class="">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?<br class=""></blockquote><br class=""></div><div class="">See chapter 6 "Development" in the documentation:</div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span><a href="https://trac.deepamehta.de/wiki/Documentation" class="">https://trac.deepamehta.de/wiki/Documentation</a></div><div class="">In particular:</div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span><a href="https://trac.deepamehta.de/wiki/DataFormat" class="">https://trac.deepamehta.de/wiki/DataFormat</a></div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span><a href="https://trac.deepamehta.de/wiki/RestApi" class="">https://trac.deepamehta.de/wiki/RestApi</a></div><div class="">Be aware that some particularities might be outdated on these pages.</div><div class="">Feel free register at the Trac and update these pages :-)</div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">Cheers,</div><div class="">Jörg</div><div class=""><br class=""></div></body></html>