Hi Robert, On 19 Sep 2016, at 21:07, Robert Schuster <[email protected]> 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
signature.asc
Description: Message signed with OpenPGP using GPGMail
-- devel mailing list [email protected] http://lists.deepamehta.de/mailman/listinfo/devel-lists.deepamehta.de
