Changes between Version 9 and Version 10 of JSONInterface


Ignore:
Timestamp:
Jun 29, 2012, 11:06:47 AM (12 years ago)
Author:
jurzua
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • JSONInterface

    v9 v10  
    66
    77||= Method name =||= Required parameters =||= Other parameters =||= Return =||= Description ||
    8 || get_ent || id || include_content (default value false) || ent || ||
    9 || get_ents || oc || || ents || ||
     8|| get_ent || id || include_content (default value false) || ent || Return the entity with id equal to 'id' ||
     9|| get_ents || oc || || ents || Return all entities where their object class equal to 'oc' ||
    1010|| get_ents_size || oc || || ents_size || ||
    11 || get_def || oc || || def || ||
    12 || get_defs || || || defs || ||
    13 || get_src_rels || id, rel_name, tar_oc || || src_rels || ||
    14 || get_tar_rels || id, rel_name, src_oc ||  || tar_rels || ||
    15 || get_atts || id || || atts || ||
    16 || get_tars_4_src_rel || src_id, rel_name, tar_id ||  include_content (default value false) || ents || ||
    17 || get_srcs_4_tar_rel || tar_id, rel_name, src_oc ||  include_content (default value false) || ents || ||
    18 || exist_rel || src_id, tar_id, rel_name || || exist_rel || ||
     11|| get_def || oc || || def || Returns a definition by its object class ||
     12|| get_defs || || || defs || Returns all definitions from the DB ||
     13|| get_src_rels || id, rel_name, tar_oc || || src_rels || Returns an array which contains the source relations of the entity with id = 'id' ||
     14|| get_tar_rels || id, rel_name, src_oc ||  || tar_rels || Returns an array which contains the target relations of the entity with id = 'id' ||
     15|| get_atts || id || || atts || Returns an array which contains the attributes of the entity with id = 'id'  ||
     16|| get_tars_4_src_rel || src_id, rel_name, tar_id ||  include_content (default value false) || ents || Returns an array entities that has an object class equals to 'tar_oc' and that are related to
     17the entity with id = 'src_id' through the relation called 'rel_name'. ||
     18|| get_srcs_4_tar_rel || tar_id, rel_name, src_oc ||  include_content (default value false) || ents || Returns a array entities that has an object class equals to 'src_oc' and that are related to
     19the entity with id = 'tar_id' through the relation called 'rel_name'. ||
     20|| exist_rel || src_id, tar_id, rel_name || || exist_rel || Returns true, if there is a relation between the entities with ids like: src_id and tar_id. ||
    1921
     22
     23== Description of Data Structures ==
     24
     25Basically, the database is composed of three kind of elements: entities, attributes and relation. These elements together form a directed graph. The entity is the central component and represent objects that are characterized by attributes and are connected to others entities by their relations. From the perspective of a entity, there are two kind of relation: source relation and target relations. A relation connects a source and a target.
     26For example, let be Z = {X is_created_by Y} a relation and X and Y two entities. For the entity X, Z is a source relation, because the source of Z is X. In the other hand, For the entity Y, Z is a target relation, because the target of Z is Y.
     27
     28Now, it will be explained, how the mentioned structures are represented by the json-response:
     29
     30= ent =
     31is a json object that represents the most basic element of the database. An entity will be always returned accompanied by the following sub-json-objects:
     32* id: the identifier of the entity in the DB.
     33* node_type: there are two kind of entities: definitions (node_type='TBox') and concrete entities (node_type='ABox').
     34These concepts derived from the ontology and means that a entity can be assigned either to an assertion set (Abox) or to a terminological set. A definition describe which kind of attributes and relation can have a concrete entity, in other words a concrete entity is a instance of a definition (like class and object in object-oriented languages).
     35* oc (object class): for a concrete entity, this attribute describes from which definition it derives.   Typical object classes of ISMI-DB are: TEXT, WITNESS, PERSON, etc.
     36* ov (own value): the label of the entity.
     37* nov (normalized own value): the normalized version of the own value.
     38* lw (light weight): an entity can or not include its attributes and (sources and target) relations.
     39If the entity does not contain the mentioned elements, the variable lw is false, in the other case it is true.
     40
     41If the variable lw, the ent would have also the following objects:
     42* attrs: is a json array, where every element is a att.
     43* src_rels: is a json array, where every element is a rel.
     44* tar_rels: is a json array, where every element is a rel.
     45
     46= att =
     47is a json object which is composed of the following elements:
     48* id: the identifier of the attribute in the DB
     49* ov: is value of the attribute.
     50* nov: is a normalized version of the own value.
     51* name: is name of the attribute.
     52* node_type: ABox/TBox
     53* content_type: a description of the own value (like text, date, etc).
     54* src_id: the identifier of the parent that can be a entity or a relation.
     55
     56= rel =
     57is a json object which is composed of the following elements:
     58* id: the identifier of the relation in the DB.
     59* name: name of the relation.
     60* atts: json array of attributes.
     61* src_oc: the object class of the source.
     62* tar_oc: the object class of the target
     63* src_id: the identifier of the source.
     64* tar_id: the identifier of the target.
    2065
    2166== Examples ==
    2267
    23 * https://openmind-ismi-dev.mpiwg-berlin.mpg.de/ismi-server/jsonInterface?method=getEntity&entId=432674
    24 {{{
    25 #!div style="font-size: 80%"
    26 Output:
    27   {{{#!python
    28 {
    29     "entity": {
    30         "id": 432674,
    31         "attributes": [
    32             {
    33                 "name": "name_translit",
    34                 "value": "ʿAbbās Wasīm Efendī"
    35             },
    36             {
    37                 "name": "url",
    38                 "value": "http://islamsci.mcgill.ca/RASI/BEA/Abbas_Wasim_Efendi_BEA.htm"
    39             }
    40         ],
    41         "targets": [
    42             {
    43                 "source": 432672,
    44                 "name": "is_prime_alias_name_of",
    45                 "target": 432674
    46             }
    47         ],
    48         "sources": [
    49             {
    50                 "source": 432674,
    51                 "name": "was_born_in",
    52                 "target": 149169
    53             }
    54         ]
    55     }
    56 }
    57   }}}
    58 }}}
     68get_ent
     69* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_ent&id=0
     70* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_ent&id=478591
     71* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_ent&id=478591&include_content=true
    5972
    60 * https://openmind-ismi-dev.mpiwg-berlin.mpg.de/ismi-server/jsonInterface?method=getCodex&codexIdentifier=437&collection=Jawāhir
    61 {{{
    62 #!div style="font-size: 80%"
    63 Output:
    64   {{{#!python
    65 {
    66     "codices": [
    67         {
    68             "id": 134176,
    69             "witnesses": [
    70                 {
    71                     "id": 55153
    72                 }
    73             ],
    74             "repository": "Azad Library",
    75             "entity": {
    76                 "attributes": [
    77                     {
    78                         "name": "identifier",
    79                         "value": "437"
    80                     }
    81                 ],
    82                 "targets": [
    83                     {
    84                         "source": 55153,
    85                         "name": "is_part_of",
    86                         "target": 134176
    87                     }
    88                 ],
    89                 "sources": [
    90                     {
    91                         "source": 134176,
    92                         "name": "is_part_of",
    93                         "target": 149134
    94                     }
    95                 ]
    96             },
    97             "collection": "Jawāhir",
    98             "identifier": "437",
    99             "country": "India",
    100             "city": "Aligarh"
    101         }
    102     ]
    103 }
    104   }}}
    105 }}}
    10673
    107 * https://openmind-ismi-dev.mpiwg-berlin.mpg.de/ismi-server/jsonInterface?method=getManuscript&entId=63326
    108 {{{
    109 #!div style="font-size: 80%"
    110 Output:
    111   {{{#!python
    112 {
    113     "responseInfo": "OK",
    114     "extended-manuscript": {
    115         "notes_on_ownership_in_codex": "",
    116         "notes_in_codex": "",
    117         "location": "Konya, Turkey",
    118         "date_calendar": "",
    119         "number_of_folios": "",
    120         "holding_library": "Yusuf Agha",
    121         "author": "Abū al-Ḥasan ʿAlī ibn ʿAbī Bakr al-Harawī",
    122         "scripts": "",
    123         "title": " Al-Tadhkira al-Harawiyya fī ḥiyal al-ḥarbiyya",
    124         "notes_on_ownership": "",
    125         "call_number": "5009",
    126         "distinguishing_features": "",
    127         "editorial_remarks": "",
    128         "signature": "",
    129         "linesPerPage": "",
    130         "abstract": "",
    131         "keywords": "",
    132         "contents": "",
    133         "collation_corrections": "",
    134         "incipit": "",
    135         "catchwords": "",
    136         "copyist": "Abū Isḥāq b. Saʿd Allāh",
    137         "written_area_dimensions": "",
    138         "secondary_literature": "",
    139         "year_calendar": "",
    140         "explicit": "",
    141         "binding": "",
    142         "writing_surface": "",
    143         "foliation": "",
    144         "page_dimensions": "",
    145         "notes": ""
    146     }
    147 }
    148   }}}
    149 }}}
     74get_ents
     75* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_ents
     76* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_ents&oc=TEXT
     77* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_ents&oc=WITNESS
     78
     79
     80get_def
     81* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_def&oc=TEXT
     82
     83get_defs
     84* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_defs
     85
     86get_src_rels
     87* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_src_rels
     88* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_src_rels&id=478591&rel_name=was_created_by&tar_oc=PERSON
     89
     90get_tar_rels
     91* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_tar_rels&id=478591&rel_name=is_exemplar_of&src_oc=WITNESS
     92
     93get_srcs_4_tar_rel
     94* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_srcs_4_tar_rel&id=478591&rel_name=is_exemplar_of&src_oc=WITNESS
     95
     96get_tars_4_src_rel
     97* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=get_tars_4_src_rel&id=63777&rel_name=is_exemplar_of&tar_oc=TEXT
     98
     99
     100is_exemplar_of
     101* https://openmind-ismi-dev.mpiwg-berlin.mpg.de/om4-ismi/jsonInterface?method=exist_rel&tar_id=478591&src_id=57738&rel_name=is_exemplar_of
     102