Project

General

Profile

Usage » History » Revision 109

Revision 108 (Bernhard Koschicek, 2020-10-20 12:17) → Revision 109/116 (Bernhard Koschicek, 2020-10-23 11:43)

h1. Usage

{{child_pages}}

{{toc}}

This site explains the different usage scenarios. The API basically can be accessed through two methods: Either from the user interface of an OpenAtlas application or, if the settings will allow it, from another application.

Please refer to the SwaggerHub documentation: https://app.swaggerhub.com/apis-docs/ctot-nondef/OpenAtlas/0.1

h1. Paths

h3. No parameters available:

* Request one entity: /api/0.1/entity/105
* Download a JSON of one entity: /api/0.1/entity/download/105
* Request list of entities of one node: /api/0.1/node_entities/26294
* Request list of entities of one node and subnodes: /api/0.1/node_entities_all/26294
* Request list of subunits of one place: /api/0.1/subunit/50505
* Request list of all subunits of one place: /api/0.1/subunit_hierarchy/50505
* URL for displaying images: /api/display/4215
** The image will only be displayed if:
### A user is logged in
### API is set on public
### IP is on the whitelist


h3. Parameters available:

* Request by code: /api/0.1/code/actor
* Request by class: /api/0.1/class/E18
* Request by latest: /api/0.1/latest/16 (int = number of entries)

* Request one or more entities: /api/0.1/query?entities=115&entities=116
* Request one or more classes: /api/0.1/query?classes=E18&classes=E31
* Request one or more codes: /api/0.1/query?items=actor&items=source
* Combine requests: /api/0.1/query?items=actor&items=source&classes=E18&classes=E31&entities=115&entities=116

h1. Parameter

The API paths also take in parameters.

h2. Sort

<pre>
<'asc', 'desc'>
</pre>
The _sort_ parameter controls the order of the results. These can be either ascending (asc) or descending (desc). To use this feature add the parameter:
<pre>?sort=<'asc','desc'></pre>

h3. Validation

If multiple _sort_ parameter are used, the first valid sort input will be used.
It does not matter if the words are uppercase or lowercase (i.e. DeSc or aSC), but the query only takes *asc* or *desc* as valid input. If no valid input is provided, the result is orders ASC.

h2. Column

<pre>
<'id', 'class_code', 'name', 'description', 'created', 'modified', 'system_type', 'begin_from', 'begin_to', 'end_from', 'end_to'>
</pre>

The _column_ parameter declares which columns in the table are sorted with the _sort_ parameter.

<pre>?column=<'id', 'class_code', 'name', 'description', 'created', 'modified', 'system_type', 'begin_from', 'begin_to', 'end_from', 'end_to'></pre>

h3. Validation

If multiple _column_ parameter are used, a list is created, by the order in which the parameters are given (i.e. ?column=name&column=description&column=id will order by name, description and id).
It does not matter if the words are uppercase or lowercase (i.e. Name, ID, DeScrIPtioN or Class_Code). If no valid input is provided, the results are ordered by name.

h2. Limit

<pre>
<number>
</pre>

The _limit_ parameter declares how many results will returned.

<pre>?limit=<number></pre>

h3. Validation

If multiple _limit_ parameter are used, the first valid _limit_ input will be used. Limit only take positive numbers.



h2. Filtering

<pre>
<=, !=, <, <=, >, >=, LIKE, IN, AND, OR, AND NOT, OR NOT>
</pre>

The _filter_ parameter is used to specify which entries should return.

<pre>?filter=<XXX></pre>



h3. Validation

_Filter_ takes a lot of different parameters in various forms. _Filter_ values need to be separated by |.
# First value has to be a concatenation operator: 'and': 'AND', 'or': 'OR', 'onot': 'OR NOT', 'anot': 'AND NOT'.
# Second value has to be the effected column: 'id', 'class_code', 'name', 'description', 'created', 'modified', 'system_type', 'begin_from', 'begin_to', 'end_from', 'end_to'.
# Third value has to be a logical operator: 'eq': '=', 'ne': '!=', 'lt': '<', 'le': '<=', 'gt': '>', 'ge': '>=', 'like': 'LIKE',
# Fourth value has to be the search term. If the 'in' operator is selected, then the search term has to be in brackets and separated by commas.

Please note, that the filter values will translate directly in SQL. For example:
<pre>
?filter=and|name|like|Ach&filter=or|id|gt|5432</pre>
will result in
<pre><code class="sql">
AND e.name LIKE %%Ach%% OR e.id > 5432
</code></pre>

<pre>
?filter=or|id|gt|150&filter=anot|id|ne|200
?filter=and|name|like|Ach
</pre>



h2. Pagination

<pre>
first=<id> OR last=<id>
</pre>

The _first_ parameter takes ids and will show every entity after and including the named id.
The _last_ parameter takes ids and will show every entity after the named id.

<pre>?first=<id></pre>
<pre>?last=<id></pre>

h3. Validation

_First_ and _last_ take only one id, which is has to be a *number*. The table will be sorted AND filtered before the pagination comes in place.
<pre>
?last=220
?first=219
</pre>



h2. Show/Hide Types

<pre>
<'when', 'types', 'relations', 'names', 'links', 'geometry', 'depictions', 'geonames', 'none'>
</pre>

The _show_ parameter will take in the key values of a json. If no value is given, every key will be filled. If a value is given, it only will show the types which are committed. If the parameter contains _none_, no additional keys/values will be shown

<pre>?show=<'when', 'types', 'relations', 'names', 'links', 'geometry', 'depictions', 'geonames', 'none'></pre>

h3. Validation

For each value a new parameter has to be set. The value will be matched against a list of keywords, so wrong input will be ignored.

<pre>
?show=when
?show=types
?show=types&show=when
?show=none
</pre>



h2. Count

<pre>
<>
</pre>

Returns a json with a number of the total count of the included entities.

<pre>?count</pre>

h3. Validation

Only _count_ will trigger the function. Count can have any numbers assigned to it, which makes no difference.

<pre>
?count
</pre>

h2. Download

<pre>
<>
</pre>

Will trigger the download of the result of the request path.

<pre>?download</pre>

h3. Validation

Only _download_ will trigger the function. Download can have anything assigned to it, but this will be discarded.

<pre>
?download
</pre>