tainacan/docs/tainacan-api.md

Tainacan Application Programming Interface

Brief Description

A REST API for Tainacan Plugin. This API uses the Wordpress REST API.

---

Routes and Endpoints

Summary

1. Collections
2. Items
3. Metadata
4. Metadatum Types
5. Item Metadata
6. Taxonomies
7. Filters
8. Filter Types
9. Terms
10. Logs
11. Others

---

Collections

1. Route wp-json/tainacan/v2/collections/(?P<collection_id>[\d]+)

   1. Endpoints:

      1. GET (Fetch a collection)      

      2. DELETE (Delete or Trash a collection and all your dependencies)

         To delete pass in body of a requisition the parameter is_permanently as true. To only trash pass false.

      3. PATCH or PUT (Update a collection)

         Example of JSON passed in body for updating a collection:    

      {
            "name": "string",
            "description": "string",
            ...
      }

2. Route wp-json/tainacan/v2/collections

   1. Endpoints:

      1. GET (Fetch all collections)

      2. POST (Create a collection).

         Example of JSON passed in body for creating a collection:

      {
            "name": "string",
            "description": "string",
            "status": "string",
            "order": "string",
            "parent": "integer",
            "slug": "string",
            "default_orderby": "string",
            "default_order": "string",
            "columns": "string",
            "default_view_mode": "string"
      }

---

Items

1. Route wp-json/tainacan/v2/collection/(?P<collection_id>[\d]+)/items

   1. Endpoints:

      1. GET (Fetch all items from a collection)

      2. POST (Create a item in a collection)

         Example of JSON passed in body for creating a item:

      {
            "title": "string",
            "description": "string",
            "status": "string",
            "terms": ["integer", "integer", ...]
      }

2. Route wp-json/tainacan/v2/items/(?P<item_id>[\d]+)

   1. Endpoints:

      1. GET (Fetch a item)

      2. DELETE (Delete or Trash a item and all your dependencies)

         To delete pass in body of a requisition the parameter is_permanently as true. To only trash pass false.

      3. PATCH or PUT (Update a item)

         Example of JSON passed in body for updating a item:    

      {
            "title": "string",
            "description": "string",
            "terms": ["integer", "integer", ...]
            ...
      }

---

Metadata

1. Route wp-json/tainacan/v2/collection/(?P<collection_id>[\d]+)/metadata

   1. Endpoints:

      1. GET (Fetch all collection metadatum)

      2. POST (Create a metadatum in collection and all it items)

         In body of requisition pass a JSON with the attributes of metadatum like:

      {
            "name": "string", 
            "description": "string",
            "metadatum_type": "string",
            "order": "string",
            "parent": "integer",
            "required": "string",
            "collection_key": "string",
            "multiple": "string",
            "cardinality": "string",
            "mask": "string",
            "default_value": "string",
            "field_type_options": "string",
      }

2. Route wp-json/tainacan/v2/collection/(?P<collection_id>[\d]+)/metadata/(?P<metadatum_id>[\d]+)

   1. Endpoints:

      1. GET (Fetch a metadatum from a collection or Fetch all metadatum values)

         To fetch all metadatum values from a metadatum of a collection in all it items, pass a query like ?fetch=all_field_values

      2. PATCH or PUT (Update a metadatum in a collection and all it items)

         In body of requisition pass a JSON with the attributes you need to update, like:

      {
            "name": "string", 
            "description": "string",
      }

3. Route wp-json/tainacan/v2/metadata

   1. Endpoints:

      1. GET (Fetch all default metadata)

      2. POST (Create a default metadatum)

         In body of requisition pass a JSON with the attributes of metadatum.

4. Route wp-json/tainacan/v2/metadata/(?P(<metadatum_id>[\d]+))

   1. Endpoints:

      1. DELETE (Trash a default metadatum)

      2. PATCH or PUT (Update a default metadatum)

         In body of requisition pass a JSON with the attributes you need to update.

---

Metadatum Types

1. Route wp-json/tainacan/v2/metadatum-types

   1. Endpoint:

      1. GET (Fetch all metadatum types)

---

Item Metadata

1. Route wp-json/tainacan/v2/item/(?P<item_id>[\d]+)/metadata/(?P<metadatum_id>[\d]+)

   1. Endpoints:

      1. PATCH or PUT (Set value of a metadata)

         In body of requisition pass a JSON with values of metadata, like:

      {
            "values": ["any", "type"]
      }

2. Route wp-json/tainacan/v2/item/(?P<item_id>[\d]+)/metadata

   1. Endpoint:

      1. GET (Fetch all item metadata, with it values)

---

Taxonomies

1. Route wp-json/tainacan/v2/taxonomies

   1. Endpoints:

      1. GET (Fetch all taxonomies)

      2. POST (Create a taxonomy)

         Example of JSON passed in body for creating a taxonomy:

      {
            "name": "string",
            "description": "string",
            "status": "string",
            "parent": "string",
            "slug": "string",
            "allow_insert": "string",
            "collections_ids": "array"
      }

2. Route wp-json/tainacan/v2/taxonomies/(?P<taxonomy_id>[\d]+)

   1. Endpoints:

      1. GET (Fetch a taxonomy)

      2. DELETE (Delete or trash a taxonomy)

         To delete pass in body of requisition the parameter is_permanently as true. To only trash pass false.

      3. PATCH or PUT (Update a taxonomy)

         Example of JSON passed in body for updating a taxonomy:    

      {
            "name": "string",
            "description": "string",
            ...
      }

3. Route wp-json/tainacan/v2/taxonomies/(?P<taxonomy_id>[\d]+)/collection/(?P<collection_id>[\d]+)

   1. Endpoints:

      1. PATCH or PUT (Add a Collection in a Taxonomy)

---

Filters

1. Route wp-json/tainacan/v2/collection/(?P<collection_id>[\d]+)/metadatum/(?P<metadatum_id>[\d]+)/filters

   1. Endpoints:

      1. POST (Create a filter)

         Example of JSON passed in body for creating a filter:

      {
            "filter_type": "string",
            "filter": {
                  "name": "string",
                  "description": "string",
                  ...
            }
      }

2. Route wp-json/tainacan/v2/filters/(?P<filter_id>[\d]+)

   1. Endpoints:

      1. GET (Fetch a filter)

      2. DELETE (Delete or trash a filter)

         To delete pass in body of requisition the parameter is_permanently as true. To only trash pass false.

      3. PATCH or PUT (Update a filter)

         Example of JSON passed in body for updating a filter:

      {
            "name": "string",
            ...
      }

3. Route wp-json/tainacan/v2/filters

   1. Endpoints:

      1. GET (Fetch all repository filters)

      2. POST (Create a filter in repository. Without metadatum and collection associations)

         Example of JSON passed in body for creating a filter:

      {
            "filter_type": "string",
            "filter": {
                  "name": "string",
                  "description": "string",
                  ...
            }
      }

4. Route wp-json/tainacan/v2/collection/(?P<collection_id>[\d]+)/filters

   1. Endpoints:

      1. GET (Fetch all collection filters)

      2. POST (Create a filter in a collection, without metadatum association)

         Example of JSON passed in body for creating a filter:

      {
            "filter_type": "string",
            "filter": {
                  "name": "string",
                  "description": "string",
                  ...
            }
      }

---

Filter Types

1. Route wp-json/tainacan/v2/filter-types

   1. Endpoint:

      1. GET (Fetch all filter types)

---

Terms

1. Route wp-json/tainacan/v2/taxonomy/(?P<taxonomy_id>[\d]+)/terms

   1. Endpoints:

      1. GET (Fetch all tems of a taxonomy)

      2. POST (Create a term in a taxonomy)

         Example of JSON passed in body for creating a term:

      {
            "name": "string",
            "user": "int",
            ...
      }

2. Route wp-json/tainacan/v2/taxonomy/(?P<taxonomy_id>[\d]+)/terms/(?P<term_id>[\d]+)

   1. Endpoints:

      1. GET (Fecth a term of a taxonomy)

      2. DELETE (Delete a term of a taxonoy)

      3. PATCH or PUT (Update a term in a taxonomy)

         Example of JSON passed in body for updating a term:

      {
            "name": "string",
            ...
      }

---

Logs

1. Route wp-json/tainacan/v2/logs

   1. Endpoints:

      1. GET (Get all logs)

2. Route wp-json/tainacan/v2/logs/(?P<log_id>[\d]+)

   1. Endpoints:

      1. GET (Get a log)

---

Others

To Create, Read, Update or Delete Media or Users you can use the default routes of Wordpress.

See about Media in Media | REST API Handbook;

See about Users in Users | REST API Handbook.