sauterl/cineast-api-changes.md

## cineast-api-changes.md

      
    Raw
  

              cineast-api-changes.md
            
          
    Cineast API Changes

To address vitrivr/cineast#163 and vitrivr/vitrivr-ng#58 the following renaming and re-organising of Cineast's REST API is proposed.
Ultimately, the renaming and re-organising should clearify what endpoints do and provide a consistent naming scheme for them.
Metadata


RENAME /api/v1/find/metadata/of/{id}/in/{domain}/with/{key} Find metadata for specific object id in given domain with given key
/api/v1/metadata/objects/by/{id}/in/{domain}/with/{key} Get metadata for a specific object id in given domain with given key, i.e. get a single metadata value


RENAME /api/v1/find/metadata/by/id/{id} Find metadata for the given object id
/api/v1/metadata/objects/by/{id} Get all metadata for the given object id


RENAME /api/v1/find/metadata/by/id Finds metadata for the given list of object ids
/api/v1/metadata/objects/by Get all metadata for the given list of object ids


RENAME /api/v1/find/metadata/in/{domain}/by/id/{domain} Find metadata for specific object id in given domain
/api/v1/metadata/objects/by/{id}/in/{domain} Get metadata for specific object id in given domain


RENAME /api/v1/find/metadata/in/{domain} Find metadata in the specified domain for all the given ids
/api/v1/metadata/objects/in/{domain} Get metadta in specified domain for given ids


RENAME /api/v1/find/metadata/with/{key}/by/id/{id} Find metadata for a given object id with specified key
/api/v1/metadata/objects/by/{id}/with/{key} Get metdata for given object id with specified key


RENAME /api/v1/find/metadata/with/{key} Find metadata for a given object id with specified key
/api/v1/metadata/objects/with/{key} Get metadata with specified key for given ids


RENAME /api/v1/find/metadata/by/segmentid/{id} Find metadata for the given segment id
/api/v1/metadata/segments/by/{id} Get metadata for the given segment id


RENAME and MOVE /api/v1/find/feature/all/by/id/{id} Find features for the given id
See Analysis


RENAME and MOVE /api/v1/find/feature/text/by/{id}/{category} Find Text for the given id and retrieval category
See Analysis


RENAME and MOVE /api/v1/find/feature/tags/by/id/{id} Find tag ids for the given id
See Analysis


Analysis


ADD /api/v1/analysis/features/all/by/{id} Get features for the given segment id
ADD /api/v1/analysis/features/text/{category}/by/{id} Get text features for given segment id and category
ADD /api/v1/analysis/features/tags/by/{id} Get tag ids for the given segment id

Object


RENAME /api/v1/find/objects/all Find all objects for a certain type
/api/v1/objects/all List all objects
RENAME /api/v1/find/object/by/id Find objects by id
/api/v1/objects/by Get objects by object id
RENAME /api/v1/find/object/by/{attribute}/{value} Find object by specified attribute value. I.e by id, name or path
/api/v1/objects/filtered/{attribute}/{value} Get objects by speicified attribute value (i.e. id, name or path)
ADD /api/v1/objects/by/{id} Get an object by its object id, convenience endpoint for /api/v1/objects/filtered/id/{id}

Segment


RENAME /api/v1/find/segments/by/id Finds segments for specified ids
/api/v1/segments/by Get segments with given segment ids


RENAME /api/v1/find/segments/by/id/{id} Finds segments for specified id
/api/v1/segments/by/{id} Get segment with segment id


RENAME /api/v1/find/segments/all/object/{id} Find segments by their media object's id
/api/v1/segments/of/object/{id} Get all segments of a speicified media object


Query

Category formerly known as Segments


RENAME /api/v1/find/segments/similar Find similar segments based on the given query
/api/v1/query/similarity Perform a (staged) similarity query


ADD /api/v1/query/temporal Perform a temporal similarity query // Not sure whether this is actually


Tag


RENAME /api/v1/find/tags/all Find all tags
/api/v1/tags/all List all tags


RENAME /api/v1/tags/by/id Find all tags by ids
/api/v1/tags/by Get all tags by their ids


REPLACE /api/v1/find/tags/by/{attribute}/{value} Find all tags specified by attribute value
See below


ADD /api/v1/tags/by/{id} Get the tag with the specified id


ADD /api/v1/tags/named/{name} Get all tags with the given name


ADD /api/v1/tags/matching/{name} Get tags matching the name. For matching, case-insensitive a left and right side truncation comparison is used. The matching tags are returned in order of their expected relevance.


Session


/api/v1/session/start Start new session for given credentials
/api/v1/session/extract/start Start extraction session
/api/v1/session/extract/new Extract new item
/api/v1/session/validate/{id} Validates the session with given id
/api/v1/session/extract/end End the active extraction session
/api/v1/session/end/{id} End the session for given id

Database

Category formerly known as Misc


RENAME /api/v1/find/boolean/column/distinct Find all distinct elements of a given column
/api/v1/database/column/distinct List all distinct elements of a given column


ADD /api/v1/database/status Get the status of the database


Status


/api/v1/status Get the status of the server

Legacy API

This is basically a copy of the OpenAPI Specifications pre-changes.
Metadata


/api/v1/find/metadata/of/{id}/in/{domain}/with/{key} Find metadata for specific object id in given domain with given key
/api/v1/find/metadata/by/id/{id} Find metadata for the given object id
/api/v1/find/metadata/by/id Finds metadata for the given list of object ids
/api/v1/find/metadata/in/{domain}/by/id/{domain} Find metadata for specific object id in given domain
/api/v1/find/metadata/in/{domain} Find metadata in the specified domain for all the given ids
/api/v1/find/metadata/with/{key}/by/id/{id} Find metadata for a given object id with specified key
/api/v1/find/metadata/with/{key} Find metadata for a given object id with specified key
/api/v1/find/metadata/by/segmentid/{id} Find metadata for the given segment id
/api/v1/find/feature/all/by/id/{id} Find features for the given id
/api/v1/find/feature/text/by/{id}/{category} Find Text for the given id and retrieval category
/api/v1/find/feature/tags/by/id/{id} Find tag ids for the given id

Object

- /api/v1/find/objects/all Find all objects for a certain type

/api/v1/find/object/by/id Find objects by id
/api/v1/find/object/by/{attribute}/{value} Find object by specified attribute value. I.e by id, name or path

Segment


/api/v1/find/segments/by/id Finds segments for specified ids
/api/v1/find/segments/by/id/{id} Finds segments for specified id
/api/v1/find/segments/all/object/{id} Find segments by their media object's id

Segments


/api/v1/find/segments/similar Find similar segments based on the given query

Tag


/api/v1/find/tags/all Find all tags
/api/v1/tags/by/id Find all tags by ids
/api/v1/find/tags/by/{attribute}/{value} Find all tags specified by attribute value

Session


/api/v1/session/start Start new session for given credentials
/api/v1/session/extract/start Start extraction session
/api/v1/session/extract/new Extract new item
/api/v1/session/validate/{id} Validates the session with given id
/api/v1/session/extract/end End the active extraction session
/api/v1/session/end/{id} End the session for given id

Misc


/api/v1/find/boolean/column/distinct Find all distinct elements of a given column

Status


/api/v1/status Get the status of the server