Skip to content

Latest commit

 

History

History
149 lines (103 loc) · 4.86 KB

API.md

File metadata and controls

149 lines (103 loc) · 4.86 KB

API

1. APPCONF

Returns the definition of the appconf.xml.

/api

2. List of all IDs

Returns a JSON list with all object IDs to identify by ID which object type a speficied object has.

/api?id=all

2.1 GET-Parameters

  • id must be equal to all.
  • optional limit defines how many objects of each type are retrieved,

3. List of objects or relations

Returns a list of all items of an object type or relation type as JSON.

For the list of objects see the newer OPENAPI documentation.

Attention: Because of performance issues only 10'000 entries are returned. If more are requested please use the limit parameter.

/api/<object-relation-type>

  • object-relation-type the ID of the object definition or the relation definition in the appconf.xml

3.1 GET-Parameters

The following parameters are for relation lists:

  • limit optional parameter. Defines how many (unordered) entries are retrieved (default value is 10'000). For relations it defines how many object entries are used for searching the relations.
  • object defines the object ID the items to be filtered by. To be used with show=list.
  • subject defines the subject ID the items to be filtered by. To be used with show=list
  • show possible values are:
    • list show relation items matching filter criteria
    • empty show all relation items

3.2 Results

Default /api/<relation-type>

  • ?date-time stamp of caching
  • ?list of relations
  • ?list?(#position) contains the following values:
    • ?absolute-resource-id of relation xml
    • ?internal-node-id of relation xml
    • ?object ID of relation
    • ?predicate value of relation
    • ?subject ID of relation
    • ?xml of relation
  • ?name of relation
  • ?object-type of relation
  • ?results-found number of relations
  • ?results-shown number of relations in list. Equals to results-found if equal or lower then the limitparameter.
  • ?subject-type of relation
  • ?type equals "relations"

3.3 Examples

  • show list of person-manuscript relations: /api/person-manuscript

4. Get object

Returns a information of a single object.

For retrieving an object see the newer OPENAPI documentation.

/api/<object-type>/<object-id>

5. Get part of an object

Returns a part of a single object as xml.

For retrieving a part of an object see the newer OPENAPI documentation.

/api/<object-type>/<object-id>/<object-part>

6. Searching

Uses the the defined search routines and shows the results ordered by score:

/api/search/<search-id>

6.1 GET-Parameters

  • q the query string to be searched for
  • optional kwic-width parameter defines the range of characters showed the kwic (key word in context) results.
  • optional limit defines how many objects for searching are retrieved, see above List of objects.
  • optional type the type of query. Possible values are:
  • optional slop the distance between words in a phrase. Used with type=phrase

6.2 Result

JSON output: /api/search/<search-id>?q=<query>

  • ?date-time stamp of the search
  • ?type equals "search"
  • ?id of search
  • ?query contains the query string
  • ?kwic-width contains the kwic-width used. Default is 30.
  • ?list contains maps of the objects with hits, see above.

6.3 Examples

  • Search for a word in all indexes (persons, places, etc.): /api/search/all-indexes?q=Berlin

  • Search for a text in manuscipt descriptions: /api/search/manuscript-descr?q=Berlin results in:

7. Caching

Due to performance some of the API calls are cached. So calls like /api/<object-type> result in a cache for all entities of <object-type> and their properties.

If data is changed and the cache can be rebuild by adding a GET parameter to the above API calls:

  • cache. Possible values are:
    • no cache is rebuild if newer data exists
    • reset cache is always rebuild (exception: cache is not rebuild if it is newer than 1 minute)