CYCLOPS (CCLP) API version v1

https://github.com/indexdata/mod-cyclops/

CYCLOPS (CCLP) API

API calls to interact with the various CCMS commands

Overview

This WSAPI provides a RESTish and FOLIO-idiomatic way of invoking the operations to be supported by the CCMS server, the data-management middleware at the heart of the CYCLOPS system. Based on section 2.3 (Commands) of the CCMS Documentation, the following commands will be supported, and will act on the specified kinds of object.

  • 2.3.1. add tag -- operates on sets (using tags and filters)
  • 2.3.2. create set -- operates on sets
  • 2.3.3. define filter -- operates on filters (using other filters)
  • 2.3.4. define tag -- operates on tags
  • 2.3.5. delete -- operates on sets (using filters and tags)
  • 2.3.6. help -- (can be ignored)
  • 2.3.7. insert -- operates on sets (using other sets, filters and tags)
  • 2.3.8. remove tag -- operates on sets (using tags and filters)
  • 2.3.9. retrieve -- operates on sets (using filters and tags)
  • 2.3.10. show filters -- operates on filters
  • 2.3.11. show sets -- operates on sets
  • 2.3.12. show tags -- operates on tags

This gives us three kinds of object that we need to represent RESTfully, and one more implied object representing the set of tags associated with a set:

  • tags (2 operations) at /cyclops/tags
  • filters (2 operations) at /cyclops/filters
  • sets (7 operations) at /cyclops/sets and individual sets at /cyclops/sets/{setName}
    • tags applied to a set at /cyclops/sets/{setName}/tag/{tagName}

The last of these paths is the most conceptually complex. The path /cyclops/sets/mike/tag/dino represents the resource "the subset of records within the set mike that are tagged with dino". POSTing to that resource can add or remove records to the subset by associating the tag with records in the wider set. (The path for this resource includes the currently redundant component /tag in case we need to extend the set API later on to address other kinds of object associated with sets.)

Implementation note. Operations on tags do not rely on any other kind of object. Operations on filters rely only on other filters. So the dependency graph is simple: we need to implement both tags and filters (in either order) before we can fully implement sets.

/cyclops

get post

Tags that can be applied to records in a set

get

Return a list of all known tags

post

Create a new tag

Create a new tag

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A tag in a CYCLOPS system, used to mark objects within a set",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The short human-readable name of the tag"
    }
  },
  "additionalProperties": false,
  "required": [
    "name"
  ]
}

Example:

{
  "name": "dino"
}

HTTP status code 204

No content is returned.

get post

Filters that can narrow down records within a set

get

Return a list of all known filters

post

Create a new filter

Create a new filter

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A filter in a CYCLOPS system, used to capture a filtering criterion",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The short human-readable name of the filter"
    },
    "cond": {
      "type": "string",
      "description": "An SQL-like WHERE condition"
    },
    "template": {
      "type": "string",
      "description": "Optionally, the name of another filter to duplicate"
    }
  },
  "additionalProperties": false,
  "required": [
    "name",
    "cond"
  ]
}

Example:

{
  "name": "jurassic",
  "cond": "143100000 <= age AND age <= 201400000",
  "template": "mesozoic"
}

HTTP status code 204

No content is returned.

get post

Sets of objects (books, films, etc.)

get

Return a list of the names of all known sets

post

Create a new set

Create a new set

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A set in a CYCLOPS system, representing a collections of objects",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The short human-readable name of the set"
    }
  },
  "additionalProperties": false,
  "required": [
    "name"
  ]
}

Example:

{
  "name": "mike"
}

HTTP status code 204

No content is returned.

get post

get

Retrieve elements of a set

post

add objects to, or remove objects from, a set

Retrieve elements of a set

URI Parameters

  • setName: required(string)

    The name of the set to retrieve from, modify or tag

Query Parameters

  • fields: required(string)

    Either * (for all fields) or a comma-separated list

  • cond: (string)

    An SQL-like WHERE condition

  • filter: (string)

    The name of a filter to apply to the set

  • tag: (string)

    The name of a tag to which to restrict the retrieved objects

  • omitTag: (string)

    The name of a tag by which to exclude objects from the retrieved

  • sort: (string)

    a comma-separated list of fields to sort the objects on. The default order is undefined if this is not specified

  • offset: (number)

    number of objects that will be skipped and not returned as part of the result. This can be useful for retrieving objects one page of data a time. Note that 'sort' is required whenever this is used

  • limit: (string)

    a maximum number of objects that will be returned

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A response to a CYCLOPS retrieve command, containing values from some fields in a set of objects",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Status of retrieveal, or 'error'"
    },
    "message": {
      "type": "string",
      "description": "Error message, only if status==error"
    },
    "fields": {
      "type": "array",
      "description": "Error message, only if status==error",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of a field included among the data rows"
          }
        },
        "additionalProperties": false,
        "required": [
          "name"
        ]
      }
    },
    "data": {
      "type": "array",
      "description": "List of returned data rows",
      "items": {
        "type": "object",
        "properties": {
          "values": {
	    "type": "array",
            "description": "XXX An array of data values, belonging to the fields named in the 'fields' top-level element",
	    "items": {
              "type": "string"
	    }
          }
        },
        "additionalProperties": false,
        "required": [
          "values"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "status"
  ]
}

Example:

{
  "status": "ok",
  "message": "XXX This message should not exist, since status != 'error'",
  "fields": [
    {
      "name": "id"
    },
    {
      "name": "author"
    },
    {
      "name": "title"
    }
  ],
  "data": [
    {
      "values": [
        "123",
        "J. R. R. Tolkien",
        "The Lord of the Rings"
      ]
    },
    {
      "values": [
        "456",
        "Douglas Adams",
        "The Hitch-Hiker's Guide to the Galaxy"
      ]
    }
  ]
}

add objects to, or remove objects from, a set

URI Parameters

  • setName: required(string)

    The name of the set to retrieve from, modify or tag

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A request to add objects to, or remove objects from, a set",
  "type": "object",
  "properties": {
    "op": {
      "type": "string",
      "description": "Operation to perform: add or remove",
      "enum": ["add", "remove"]
    },
    "from": {
      "type": "string",
      "description": "Name of the set from which records are to be added to this one. Mandatory for 'add', prohibited for 'delete'"
    },
    "cond": {
      "type": "string",
      "description": "An SQL-like WHERE condition specifying the selection of records included in the operation"
    },
    "filter": {
      "type": "string",
      "description": "The name of a filter to be applied to selection of records included in the operation"
    },
    "tag": {
      "type": "string",
      "description": "A comma-separated list of the names of tags, specifying that only those selected records with any of the tags will be be included in the operation"
    },
    "omitTag": {
      "type": "string",
      "description": "A comma-separated list of the names of tags, specifying that only those selected records without any of the tags will be be included in the operation"
    }
  },
  "additionalProperties": false,
  "required": [
    "op"
  ]
}

Examples:

add:

{
  "op": "add",
  "from": "mike",
  "cond": "date >= \"2025-01-01\"",
  "filter": "jurassic",
  "tag": "dino,ptero",
  "omitTag": "croc"
}

remove:

{
  "op": "remove",
  "cond": "date < \"2025-01-01\"",
  "filter": "cretaceous",
  "tag": "dino",
  "omitTag": "ptero,croc"
}

HTTP status code 204

No content is returned.

post

post

add tag to, or remove tag from, objects within in a set

add tag to, or remove tag from, objects within in a set

URI Parameters

  • setName: required(string)

    The name of the set to retrieve from, modify or tag

  • tagName: required(string)

    The name of the tag to add or remove to object within the set. The path /cyclops/sets/mike/tag/dino represents the resource "the set of records that are tagged with dino in the set mike.

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A request to add a tag to, or remove a tag from from, objects within a set",
  "type": "object",
  "properties": {
    "op": {
      "type": "string",
      "description": "Operation to perform: add or remove",
      "enum": ["add", "remove"]
    },
    "cond": {
      "type": "string",
      "description": "An SQL-like WHERE condition specifying the selection of records included in the operation"
    },
    "filter": {
      "type": "string",
      "description": "The name of a filter to be applied to selection of records included in the operation"
    }
  },
  "additionalProperties": false,
  "required": [
    "op"
  ]
}

Examples:

add:

{
  "op": "add",
  "cond": "title LIKE \"%saur\"",
  "filter": "jurassic"
}

remove:

{
  "op": "remove",
  "cond": "author LIKE \"%taylor%\"",
  "filter": "cretaceous"
}

HTTP status code 204

No content is returned.