[Tagging] Single taxonomy view API #75

Story

"As a taxonomy administrator, I want to see all the tags available for use with a closed taxonomy, so that I can see the taxonomy's structure in the management interface."

"As a taxonomy administrator, I want to see all the metadata for a single taxonomy, so that I can review and edit it in the management interface."

Description

Builds on the REST API created for #73, which added:

• /tagging/rest_api/v1/taxonomy/<id>/ -- returns the taxonomy metadata

Implement a REST API that allows retrieving a taxonomy's tags given a taxonomy ID. The purpose of this API is to allow visualization of the taxonomies in the management interface.

For this task, the "taxonomy metadata" can be edited (according to rules/permissions), but the "tags" data will be read-only. This view will eventually evolve to allow taxonomy tag editing in later phases of the project, but for MVP, we only allow editing via the import/export APIs.

Define the REST API representation of taxonomies (serialized structure of a taxonomy and its tags) and document it on the REST API.

Completion criteria

Add REST API for oel_tagging:

• GET /tagging/rest_api/v1/taxonomy/<id>/tags/?page_size=<size>&page=<p>
  Returns a paginated list of existing Tags linked to a given Taxonomy, including their depth in the taxonomy tree (default 0) and parent Tag, if any.
  Paginate this data, with a high default MAX_PAGE_SIZE, e.g. 1000, to allow most of the MVP's closed taxonomies to retrieve all of their tags in one hit. Taxonomies with more tags than this will have to use pagination, and so this endpoint should support that too.

Bring the above REST API into content_tagging under this path:

• GET /api/content_tagging/v1/taxonomy/<id>/tags/?page_size=<size>&page=<p>

Pagination

Use the same Pagination class and similar serialized response classes that were added for #74.

For your tests, feel free to set a more reasonable MAX_PAGE_SIZE to test the next page behavior.

Data returned

Data to be returned by the REST endpoint:

• List of Tags metadata linked to the taxonomy <id>: id, value, parent_id, external_id, depth (calculated)
  • Return the Tag data in a way that makes it possible for the frontend to render a tree of tags.
  • Omit any Tags which are not available for use with the taxonomy (e.g. system-defined Language tags that fall outside of the defined settings.LANGUAGES)
• Pagination: ref DRF Pagination
  • Include page and num_pages in the serialized data.
  • If taxonomy.tag_set.count() > page_size, return the next page URL to fetch more tags.
    If we've returned all the tags, return an empty next URL.
  • Set a high MAX_PAGE_SIZE e.g. 1000, and use that as the default page_size.

Out of scope:

• No need to return free-text ObjectTags -- we only need Tags here.
• No need to return "all potential tags" for dynamic taxonomies. E.g. for ModelSystemDefinedTaxonomies, it's ok that the only Tags returned are ones that were created while tagging objects.

Behavioral specifications

Suppose the Open edX instance has these taxonomies:

• system-defined language taxonomy: st1 (enabled), st2 (disabled), each containing 2000 tags
• 2 closed taxonomies created by taxonomy admins: t1 (enabled), t2 (disabled), each containing 100 tags
• 2 free-text taxonomies created by taxonomy admins: o1 (enabled), o2 (disabled)

Suppose the pagination defaults are:

• page_size = 1000
• max_page_size = 1000
• page = 1

and the following users:

• userA: non-staff
• userS: global staff user

GET /tagging/rest_api/v1/taxonomy/<id>/tags/

• When userA requests ^ for st1 or t1 or `o1, they receive metadata for that taxonomy, plus a list of max 1000 tags metadata and pagination data.
• When userA requests ^ for st2 or t2 or o2, they receive a "permission denied" (or 404 is fine)
• When userS requests ^ for any taxonomy, they receive the taxonomy metadata, plus a list of max 1000 tags metadata and pagination data.

GET /tagging/rest_api/v1/taxonomy/<id>/tags/?page=2

• When userA or user S requests ^, they receive metadata for that taxonomy, plus the list of tags 1001 - 2000 and pagination data.

POST/PUT/PATCH /tagging/rest_api/v1/taxonomy/<id>/tags/ -- not allowed for anyone yet

• When any user requests ^ for any taxonomy, they receive a "permission denied"

Documentation updates & improvements criteria

• API endpoint and its parameters should be well-documented
• Any decisions relevant to this endpoint should be documented as ADRs.

Relevant PRs/repositories

• oel_tagging: https://github.com/openedx/openedx-learning, cf Taxonomy view/management REST APIs openedx-core#63
• content_tagging: https://github.com/openedx/edx-platform, cf feat: add taxonomies for org api openedx-platform#32871