| Version 9 (modified by jri, 13 years ago) (diff) |
|---|
DeepaMehta REST API
The DeepaMehta application service is accessible via a REST API.
About the REST API:
All requests return application/json data.
For requests that take data in the request body: The data is expected to be of type application/json as well. So, don’t forget to set the request’s Content-Type header accordingly. Otherwise an error is returned (as application/x-www-form-urlencoded is used as the default).
About the curl examples:
The curl examples are ready for being pasted into a terminal. However, the IDs must be adjusted to your actual DB content. Hint: to determine a topic's or association's ID click it in the webclient and read the console log.
In order to make the responses more readable the curl examples make use of the jsonpretty tool. Jsonpretty is installable as a Ruby gem. See http://github.com/nicksieger/jsonpretty.
Topics
Get topic by ID
GET /core/topic/<topic ID>[?fetch_composite=true/false]
The default for fetch_composite is true.
Example 1: Getting a topic with its composite value
curl localhost:8080/core/topic/2676 | jsonpretty
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 2676,
"uri": "",
"type_uri": "dm4.notes.note",
"value": "What is DeepaMehta?",
"composite": {
"dm4.notes.title": "What is DeepaMehta?",
"dm4.notes.text": "<p>DeepaMehta is a think tool.</p>"
}
}
For details about the topic format see DataFormat#Topic.
Example 2: Getting a topic without its composite value
curl localhost:8080/core/topic/55?fetch_composite=false | jsonpretty
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 2676,
"uri": "",
"type_uri": "dm4.notes.note",
"value": "What is DeepaMehta?",
"composite": {
}
}
If the topic doesn’t exist an error 500 Retrieving topic xy failed is returned. (The error response might become more HTTP/REST conform in the furure.)
Create topic
POST /core/topic <the topic to create>
For details about the topic format see DataFormat#Topic.
For a create operation not all properties are involved:
| Property | Mandatory / Optional |
|---|---|
| id | Do not provide an ID. The ID will be system-generated. |
| uri | Optional. Default URI is an empty string. |
| type_uri | Mandatory. |
| value | For a simple topic: Optional. Default value is an empty string. You can change the value later on through an update operation. For a complex topic: Do not specify a value. The value will be system-generated. |
| composite | For a complex topic: Optional. Default composite is an empty object. You can change the composite later on through an update operation. For a simple topic: Do not specify a composite. |
Example 1: Creating a simple topic
curl localhost:8080/core/topic -i \
-X POST \
-H Content-Type:application/json \
-d '{type_uri: "dm4.contacts.city", value: "Port-au-Prince"}' \
| jsonpretty
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3448,
"uri": "",
"type_uri": "dm4.contacts.city",
"value": "Port-au-Prince",
"composite": {
}
}
Example 2: Creating a complex topic
curl localhost:8080/core/topic -i \
-X POST \
-H Content-Type:application/json \
-d '{type_uri: "dm4.notes.note",
composite: {
dm4.notes.title: "My title",
dm4.notes.text: "<p>My test text here<p>"}}' \
| jsonpretty
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 3298,
"uri": "",
"type_uri": "dm4.notes.note",
"value": "My title",
"composite": {
"dm4.notes.title": "My title",
"dm4.notes.text":"<p>My test text here<p>"
}
}
Associations
Topic Types
Getting all topic type URIs
GET /core/topictype
Example
curl localhost:8080/core/topictype -i | jsonpretty
Response:
HTTP/1.1 200 OK Content-Type: application/json [ "dm4.contacts.address", "dm4.contacts.address_entry", "dm4.contacts.address_label", "dm4.contacts.city", "dm4.contacts.country", "dm4.contacts.email_address", "dm4.contacts.first_name", "dm4.contacts.institution", "dm4.contacts.institution_name", "dm4.contacts.last_name", "dm4.contacts.person", "dm4.contacts.person_name", "dm4.contacts.phone_entry", "dm4.contacts.phone_label", "dm4.contacts.phone_number", "dm4.contacts.postal_code", "dm4.contacts.street", "dm4.core.assoc_type", "dm4.core.cardinality", "dm4.core.data_type", "dm4.core.index_mode", "dm4.core.meta_meta_type", "dm4.core.meta_type", "dm4.core.plugin", "dm4.core.plugin_migration_nr", "dm4.core.plugin_name", "dm4.core.plugin_symbolic_name", "dm4.core.role_type", "dm4.core.topic_type", "dm4.files.content", "dm4.files.file", "dm4.files.file_name", "dm4.files.folder", "dm4.files.folder_name", "dm4.files.media_type", "dm4.files.path", "dm4.files.size", "dm4.notes.note", "dm4.notes.text", "dm4.notes.title", "dm4.topicmaps.description", "dm4.topicmaps.name", "dm4.topicmaps.topicmap", "dm4.topicmaps.visibility", "dm4.topicmaps.x", "dm4.topicmaps.y", "dm4.webbrowser.url", "dm4.webbrowser.web_resource", "dm4.webbrowser.web_resource_description", "dm4.webbrowser.webpage", "dm4.webclient.add_to_create_menu", "dm4.webclient.color", "dm4.webclient.editable", "dm4.webclient.icon", "dm4.webclient.is_searchable_unit", "dm4.webclient.js_field_renderer_class", "dm4.webclient.js_page_renderer_class", "dm4.webclient.rows", "dm4.webclient.search", "dm4.webclient.search_result", "dm4.webclient.search_term", "dm4.webclient.view_config", "dm4.webclient.viewable", "dm4.workspaces.description", "dm4.workspaces.name", "dm4.workspaces.workspace" ]
Getting a topic type
GET /core/topictype/<Topic Type URI>
Example
curl localhost:8080/core/topictype/dm4.webbrowser.webpage -i | jsonpretty
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1008,
"uri": "dm4.webbrowser.webpage",
"type_uri": "dm4.core.topic_type",
"value": "Webpage",
"composite": {
},
"data_type_uri": "dm4.core.composite",
"index_mode_uris": [
],
"assoc_defs": [
{
"id": 1013,
"uri": "dm4.webbrowser.url",
"assoc_type_uri": "dm4.core.aggregation_def",
"whole_topic_type_uri": "dm4.webbrowser.webpage",
"whole_role_type_uri": "dm4.core.whole",
"whole_cardinality_uri": "dm4.core.one",
"part_topic_type_uri": "dm4.webbrowser.url",
"part_role_type_uri": "dm4.core.part",
"part_cardinality_uri": "dm4.core.one",
"view_config_topics": [
]
}
],
"view_config_topics": [
{
"id": 1025,
"uri": "",
"type_uri": "dm4.webclient.view_config",
"value": "WebpageRenderer",
"composite": {
"dm4.webclient.js_page_renderer_class": "WebpageRenderer"
}
}
]
}
For details about the topic type format see DataFormat#TopicType.
Association Types
Getting all association type URIs
GET /core/assoctype
Example
curl localhost:8080/core/assoctype -i | jsonpretty
Response:
HTTP/1.1 200 OK Content-Type: application/json [ "dm4.core.aggregation", "dm4.core.aggregation_def", "dm4.core.association", "dm4.core.composition" "dm4.core.composition_def", "dm4.core.instantiation", "dm4.core.sequence", "dm4.topicmaps.association_mapcontext", "dm4.topicmaps.topic_mapcontext", "dm4.webclient.search_result_item", "dm4.workspaces.workspace_context", ]
