TaxonomyTerm trees REST API for Invenio Applications

Run the following commands to bootstrap your environment

git clone https://github.com/oarepo/flask_taxonomies
cd flask_taxonomies
pip install -e .

Once you have installed your DBMS, run the following to create your app's database tables and perform the initial migration

invenio db init create
invenio alembic upgrade heads
invenio run

>>> from flask_taxonomies.models import Taxonomy, TaxonomyTerm
>>> # To create Taxonomy:
>>> t = Taxonomy.create_taxonomy(code='taxcode')
>>> # To create TaxonomyTerm
>>> term = t.create_term(slug='slug', extra_data={})
>>> another = t.create_term(slug='another', extra_data={})
>>> # To create TaxonomyTerm within another
>>> term2 = term.create_term(slug='slug1', extra_data={})
>>> # To get taxonomy by code
>>> t = Taxonomy.get('taxcode')
>>> # To list taxonomy top-level terms
>>> terms = list(t.roots)
>>> # To get term from taxonomy
>>> term = t.get_term('slug')
>>> # To get term and taxonomy from path
>>> t, term = Taxonomy.find_taxonomy_and_term('/taxcode/taxterm')
>>> # To move term to a different place
>>> term.move(another, MovePosition.INSIDE) # moves term to '/taxcode/another/slug/'
>>> # To delete term and its descendants
>>> term.delete()
>>> # To update Taxonomy/TaxonomyTerm
>>> t.update(extra_data={'updated': true})
>>> # To delete Taxonomy
>>> db.session.delete(t)

To list available taxonomies

curl -X GET https://localhost:5000/taxonomies/
> [{'code': ..., 'extra_data': ...}, ...]

To create taxonomy

curl -X POST \
  https://localhost:5000/taxonomies/ \
  -d '{"code": "...", "extra_data": "{...}"}'

To create a term in taxonomy

curl -X POST \
  https://localhost:5000/taxonomies/<taxonomy-code>/<taxonomy-parent-term-path>/ \
  -d '{"title": {"en": ..., ...}, "slug": "..."}

To list top-level terms in a taxonomy

curl -X GET https://localhost:5000/taxonomies/<taxonomy-code>/
> [{'slug': ..., ...}, {'slug': ..., ...}, ...]

To get Taxonomy Term details

curl -X GET https://localhost:5000/taxonomies/<taxonomy-code>/<taxonomy-term-path>/
> {'slug': ..., 'title': ..., 'extra_data', ..., 'children': [...], ...}

Delete taxonomy (including all its terms)

curl -X DELETE \
  https://localhost:5000/taxonomies/<taxonomy-code>

Delete taxonomy term (including all its childrens)

curl -X DELETE \
  https://localhost:5000/taxonomies/<taxonomy-code>/<taxonomy-term-path>/

Update taxonomy extra data

curl -X PATCH \
    https://localhost:5000/taxonomies/<taxonomy-code>/ \
    -d '{"extra_data":"{...}"}'

Update taxonomy term data

curl -X PATCH \
    https://localhost:5000/taxonomies/<taxonomy-code>/<taxonomy-term-path>/ \
    -d '{"title":"{...}", "extra_data":"{...}"}'

Move taxonomy term (or whole term subtree) inside, before or after another term

curl -X POST \
    https://localhost:5000/taxonomies/<taxonomy-code>/<taxonomy-term-path>/ \
    -H 'Destination: https://localhost:5000/taxonomies/<taxonomy-or-term-path>' \
    -H 'Destination-Order: inside|before|after' \
    -H 'Content-Type: application/vnd.move'

Note: in case of taxonomy path, only "inside" is allowed.