CYCLOPS (CCLP) API version v1

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

CYCLOPS (CCLP) API

API calls to interact with the various CCMS commands

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. create 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}/tags/{tagName}

The last of these paths is the most conceptually complex. The path /cyclops/sets/mike/tags/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 /tags 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

/cyclops/version get

The version of the running server

get

Return the VCS revision that the running server was built from

/cyclops/tags 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

Return a list of all known tags

Response

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An object containing a list of zero or more tag names",
  "type": "object",
  "properties": {
    "tags": {
      "description": "The names of the known tags",
      "type": "array",
      "items": {
        "type": "string",
        "description": "The short human-readable name of a tag"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "tags"
  ]
}

Example:

{
  "tags": [
    "dino",
    "ptero",
    "croc"
  ]
}

Create a new tag

Request
Response

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.

/cyclops/filters get post

Filters that can narrow down records within a set

get

Return a list of all known filters, with their projects and definitions

post

Create a new filter

Return a list of all known filters, with their projects and definitions

Response

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An object containing a list of zero or more filters",
  "type": "object",
  "properties": {
    "filters": {
      "description": "The known filters, each with the project that it belongs to",
      "type": "array",
      "items": {
        "type": "object",
        "description": "A filter, in the project that it belongs to",
        "properties": {
          "project": {
            "type": "string",
            "description": "The name of the project that the filter belongs to"
          },
          "filter": {
            "type": "string",
            "description": "The short name of the filter, unique within its project"
          },
          "definition": {
            "type": "string",
            "description": "The definition of the filter, an SQL-like WHERE condition"
          }
        },
        "additionalProperties": false,
        "required": [
          "project",
          "filter",
          "definition"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "filters"
  ]
}

Example:

{
  "filters": [
    {
      "project": "korea_lit",
      "filter": "jurassic",
      "definition": "143100000 <= age AND age <= 201400000"
    },
    {
      "project": "korea_lit",
      "filter": "cretaceous",
      "definition": "66000000 <= age AND age <= 143100000"
    }
  ]
}

Create a new filter

Request
Response

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.

/cyclops/sets get post

Sets of objects (books, films, etc.)

get

Return a list of all known sets, with their projects and titles

post

Create a new set, with an optional title

Return a list of all known sets, with their projects and titles

Response

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An object containing a list of zero or more sets",
  "type": "object",
  "properties": {
    "sets": {
      "description": "The known sets, each with the project that it belongs to",
      "type": "array",
      "items": {
        "type": "object",
        "description": "A set, in the project that it belongs to",
        "properties": {
          "project": {
            "type": "string",
            "description": "The name of the project that the set belongs to"
          },
          "set": {
            "type": "string",
            "description": "The short name of the set, unique within its project"
          },
          "title": {
            "type": "string",
            "description": "The human-readable title of the set"
          }
        },
        "additionalProperties": false,
        "required": [
          "project",
          "set",
          "title"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "sets"
  ]
}

Example:

{
  "sets": [
    {
      "project": "korea_lit",
      "set": "mike",
      "title": "Mike's working set"
    },
    {
      "project": "korea_lit",
      "set": "test",
      "title": "Test data"
    },
    {
      "project": "dinosaurs",
      "set": "uob",
      "title": "Holdings of the University of Bath"
    }
  ]
}

Create a new set, with an optional title

Request
Response

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 machine-readable name of the set"
    },
    "title": {
      "type": "string",
      "description": "The longer human-readable title of the set"
    }
  },
  "additionalProperties": false,
  "required": [
    "name"
  ]
}

Example:

{
  "name": "mike",
  "title": "Mike's working set"
}

HTTP status code 204

No content is returned.

/cyclops/sets/{setName} get delete

get

Retrieve elements of a set

delete

Delete a set

Retrieve elements of a set

Request
Response

URI Parameters

setName: required(string)
The name of the set to retrieve from, modify, delete 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
countOnly: (boolean)
If present and true, then no records are returned but an estimated count of how many records match the specified criteria. Perhaps surprisingly, this can take longer than actually retrieving some slice of the records.

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": "A message from CCMS, typically an error message when status=='error'. The field is always present, but may be empty when there is nothing to report."
    },
    "fields": {
      "type": "array",
      "description": "Descriptions of the fields whose values appear in each data row",
      "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": "An array of data values, belonging to the fields named in the 'fields' top-level element. Values are whatever type CCMS returns for the field, so a value may be a string, number, boolean or null.",
	    "items": {
              "type": ["string", "number", "boolean", "null"]
	    }
          }
        },
        "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"
      ]
    }
  ]
}

/cyclops/sets/{setName}/add post

post

add objects to a set

Request
Response

URI Parameters

setName: required(string)
The name of the set to retrieve from, modify, delete or tag

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A request to add objects to a set",
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "Name of the set from which records are to be added to this one"
    },
    "cond": {
      "type": "string",
      "description": "An SQL-like WHERE condition specifying the selection of records to be added"
    },
    "filter": {
      "type": "string",
      "description": "The name of a filter to be applied to selection of records to be added"
    },
    "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 added"
    },
    "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 added"
    },
    "limit": {
      "type": "string",
      "description": "A maximum number of objects that will be added to the set"
    }
  },
  "additionalProperties": false,
  "required": [
    "from"
  ]
}

Example:

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

HTTP status code 204

No content is returned.

/cyclops/sets/{setName}/remove post

post

remove objects from a set

Request
Response

URI Parameters

setName: required(string)
The name of the set to retrieve from, modify, delete or tag

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A request to remove objects from a set",
  "type": "object",
  "properties": {
    "cond": {
      "type": "string",
      "description": "An SQL-like WHERE condition specifying the selection of records to be deleted"
    },
    "filter": {
      "type": "string",
      "description": "The name of a filter to be applied to selection of records to be deleted"
    },
    "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 deleted"
    },
    "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 deleted"
    }
  },
  "additionalProperties": false
}

Example:

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

HTTP status code 204

No content is returned.

/cyclops/sets/{setName}/tags/{tagName} post

post

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

Request
Response

URI Parameters

setName: required(string)
The name of the set to retrieve from, modify, delete or tag
tagName: required(string)
The name of the tag to add or remove to object within the set. The path /cyclops/sets/mike/tags/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.

/cyclops/sets/{setName}/batch post

post

Apply the same field-changes to multiple records within a set at once

Request
Response

URI Parameters

setName: required(string)
The name of the set to retrieve from, modify, delete or tag

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A request to apply the same field-changes to multiple records within a set at once",
  "type": "object",
  "properties": {
    "ids": {
      "type": "array",
      "description": "The identifiers of the records within the set to update",
      "items": {
        "type": "string"
      }
    },
    "changes": {
      "type": "object",
      "description": "The field-values to set on all of the specified records",
      "properties": {
        "decision": {
          "type": "boolean",
          "description": "Whether the records have been approved"
        },
        "fund": {
          "type": "string",
          "description": "The name of the fund associated with the records"
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "ids",
    "changes"
  ],
  "additionalProperties": false
}

Example:

{
  "ids": ["7", "8", "9"],
  "changes": {
    "decision": true
  }
}

HTTP status code 204

No content is returned.

/cyclops/sets/{setName}/{recordId} post

post

Update the fields of a single record within a set

Request
Response

URI Parameters

setName: required(string)
The name of the set to retrieve from, modify, delete or tag
recordId: required(string)
The identifier of the record within the set to update

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A request to update the fields of a single record within a set",
  "type": "object",
  "properties": {
    "decision": {
      "type": "boolean",
      "description": "Whether the record has been approved"
    },
    "fund": {
      "type": "string",
      "description": "The name of the fund associated with the record"
    }
  },
  "additionalProperties": false
}

Example:

{
  "decision": true,
  "fund": "palci"
}

HTTP status code 204

No content is returned.

/cyclops/projects get post

The projects in the system, in which collaborative collection management takes place

get

Return a brief list of all known projects

post

Create a new project

Return a brief list of all known projects

Response

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A list of zero or more projects",
  "type": "object",
  "properties": {
    "projects": {
      "description": "A list of the projects",
      "type": "array",
      "items": {
	"type": "object",
	"$ref": "project-schema.json"
      }
    }
  }
}

Example:

{
  "projects": [
    {
      "id": "palci_slavic",
      "name": "Slavic studies",
      "action": {
	"id": "123",
	"name": "Purchase"
      }
    },
    {
      "id": "lit_nk",
      "name": "Literature of North Korea",
      "action": {
	"id": "654",
	"name": "Weed"
      }
    },
    {
      "id": "ukr1",
      "name": "Ukrainian Culture",
      "action": {
	"id": "987",
	"name": "Digitize"
      }
    }
  ]
}

Create a new project

Request
Response

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A single project in detail",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The identifier of the project, e.g. a slug, used as the {id} part in the paths of WSAPI endpoints that operate on individual projects."
    },
    "name": {
      "type": "string",
      "description": "Human-readable name"
    },
    "action": {
      "type": "object",
      "description": "At the moment, self-documentation is all we can do: see CYCLOPS-12",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier of the action"
        },
        "name": {
          "type": "string",
          "description": "Human-readable name of the action"
        }
      },
      "additionalProperties": false
    },
    "mou_link": {
      "type": "string",
      "format": "uri",
      "description": "An optional link to a memorandom of understanding"
    },
    "funds": {
      "type": "array",
      "description": "A list of the project's funds which can be used to action spectres",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the fund"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the fund"
          }
        },
        "additionalProperties": false
      }
    },
    "people": {
      "type": "array",
      "description": "The people associated with the project and their roles",
      "items": {
        "type": "object",
        "description": "A single person associated with the project",
        "required": [
          "xid",
          "role"
        ],
        "properties": {
          "xid": {
            "type": "string",
            "description": "An external identified, opaque to CCMS, of a user in the system that is communicating with CCMS, with user administation being handled by that system"
          },
          "role": {
            "type": "string",
            "description": "One of a small set of roles that a person have in a project (e.g. 'admin', 'editor', 'viewer')"
          }
        },
        "additionalProperties": false
      }
    },
    "origins": {
      "type": "array",
      "description": "The locations that can act as origins for the action associated with this project",
      "items": {
        "type": "object",
	"$ref": "location-schema.json"
      }
    },
    "destinations": {
      "type": "array",
      "description": "The locations that can be destinations for the action associated with this project",
      "items": {
        "type": "object",
	"$ref": "location-schema.json"
      }
    },
    "tracks": {
      "type": "array",
      "description": "The tracks within the project that a given spectre can be associated with",
      "items": {
        "type": "object",
        "description": "A singe track within the project",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the track"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the track"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "id"
  ]
}

Example:

{
  "id": "palci_slavic",
  "name": "Slavic studies",
  "action": {
    "id": "123",
    "name": "Purchase"
  },
  "mou_link": "https://www.miketaylor.org.uk/dino/pubs/",
  "funds": [
    {
      "id": "345",
      "name": "PALCI cultural preservation"
    },
    {
      "id": "456",
      "name": "Coalition for Slavic literature"
    }
  ],
  "people": [
    {
      "xid": "p567",
      "role": "Admin"
    },
    {
      "xid": "p678",
      "role": "`Visionary"
    }
  ],
  "origins": [
    {
      "id": "789",
      "name": "Lehigh"
    },
    {
      "id": "890",
      "name": "NYU"
    }
  ],
  "destinations": [
    {
      "id": "901",
      "name": "CLOCKSS"
    }
  ],
  "tracks": [
    {
      "id": "12",
      "name": "Offsite"
    },
    {
      "id": "123",
      "name": "Reserve"
    },
    {
      "id": "234",
      "name": "Stacks"
    }
  ]
}

HTTP status code 204

No content is returned.

/cyclops/projects/{projectId} get delete put

get

Fetch a full project

delete

Delete a project

put

Modify a project

Fetch a full project

Request
Response

URI Parameters

projectId: required(string)
The machine-readable identifier of the project

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A single project in detail",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The identifier of the project, e.g. a slug, used as the {id} part in the paths of WSAPI endpoints that operate on individual projects."
    },
    "name": {
      "type": "string",
      "description": "Human-readable name"
    },
    "action": {
      "type": "object",
      "description": "At the moment, self-documentation is all we can do: see CYCLOPS-12",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier of the action"
        },
        "name": {
          "type": "string",
          "description": "Human-readable name of the action"
        }
      },
      "additionalProperties": false
    },
    "mou_link": {
      "type": "string",
      "format": "uri",
      "description": "An optional link to a memorandom of understanding"
    },
    "funds": {
      "type": "array",
      "description": "A list of the project's funds which can be used to action spectres",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the fund"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the fund"
          }
        },
        "additionalProperties": false
      }
    },
    "people": {
      "type": "array",
      "description": "The people associated with the project and their roles",
      "items": {
        "type": "object",
        "description": "A single person associated with the project",
        "required": [
          "xid",
          "role"
        ],
        "properties": {
          "xid": {
            "type": "string",
            "description": "An external identified, opaque to CCMS, of a user in the system that is communicating with CCMS, with user administation being handled by that system"
          },
          "role": {
            "type": "string",
            "description": "One of a small set of roles that a person have in a project (e.g. 'admin', 'editor', 'viewer')"
          }
        },
        "additionalProperties": false
      }
    },
    "origins": {
      "type": "array",
      "description": "The locations that can act as origins for the action associated with this project",
      "items": {
        "type": "object",
	"$ref": "location-schema.json"
      }
    },
    "destinations": {
      "type": "array",
      "description": "The locations that can be destinations for the action associated with this project",
      "items": {
        "type": "object",
	"$ref": "location-schema.json"
      }
    },
    "tracks": {
      "type": "array",
      "description": "The tracks within the project that a given spectre can be associated with",
      "items": {
        "type": "object",
        "description": "A singe track within the project",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the track"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the track"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "id"
  ]
}

Example:

{
  "id": "palci_slavic",
  "name": "Slavic studies",
  "action": {
    "id": "123",
    "name": "Purchase"
  },
  "mou_link": "https://www.miketaylor.org.uk/dino/pubs/",
  "funds": [
    {
      "id": "345",
      "name": "PALCI cultural preservation"
    },
    {
      "id": "456",
      "name": "Coalition for Slavic literature"
    }
  ],
  "people": [
    {
      "xid": "p567",
      "role": "Admin"
    },
    {
      "xid": "p678",
      "role": "`Visionary"
    }
  ],
  "origins": [
    {
      "id": "789",
      "name": "Lehigh"
    },
    {
      "id": "890",
      "name": "NYU"
    }
  ],
  "destinations": [
    {
      "id": "901",
      "name": "CLOCKSS"
    }
  ],
  "tracks": [
    {
      "id": "12",
      "name": "Offsite"
    },
    {
      "id": "123",
      "name": "Reserve"
    },
    {
      "id": "234",
      "name": "Stacks"
    }
  ]
}

Modify a project

Request
Response

URI Parameters

projectId: required(string)
The machine-readable identifier of the project

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A single project in detail",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The identifier of the project, e.g. a slug, used as the {id} part in the paths of WSAPI endpoints that operate on individual projects."
    },
    "name": {
      "type": "string",
      "description": "Human-readable name"
    },
    "action": {
      "type": "object",
      "description": "At the moment, self-documentation is all we can do: see CYCLOPS-12",
      "required": [
        "id",
        "name"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier of the action"
        },
        "name": {
          "type": "string",
          "description": "Human-readable name of the action"
        }
      },
      "additionalProperties": false
    },
    "mou_link": {
      "type": "string",
      "format": "uri",
      "description": "An optional link to a memorandom of understanding"
    },
    "funds": {
      "type": "array",
      "description": "A list of the project's funds which can be used to action spectres",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the fund"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the fund"
          }
        },
        "additionalProperties": false
      }
    },
    "people": {
      "type": "array",
      "description": "The people associated with the project and their roles",
      "items": {
        "type": "object",
        "description": "A single person associated with the project",
        "required": [
          "xid",
          "role"
        ],
        "properties": {
          "xid": {
            "type": "string",
            "description": "An external identified, opaque to CCMS, of a user in the system that is communicating with CCMS, with user administation being handled by that system"
          },
          "role": {
            "type": "string",
            "description": "One of a small set of roles that a person have in a project (e.g. 'admin', 'editor', 'viewer')"
          }
        },
        "additionalProperties": false
      }
    },
    "origins": {
      "type": "array",
      "description": "The locations that can act as origins for the action associated with this project",
      "items": {
        "type": "object",
	"$ref": "location-schema.json"
      }
    },
    "destinations": {
      "type": "array",
      "description": "The locations that can be destinations for the action associated with this project",
      "items": {
        "type": "object",
	"$ref": "location-schema.json"
      }
    },
    "tracks": {
      "type": "array",
      "description": "The tracks within the project that a given spectre can be associated with",
      "items": {
        "type": "object",
        "description": "A singe track within the project",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the track"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the track"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "id"
  ]
}

Example:

{
  "id": "palci_slavic",
  "name": "Slavic studies",
  "action": {
    "id": "123",
    "name": "Purchase"
  },
  "mou_link": "https://www.miketaylor.org.uk/dino/pubs/",
  "funds": [
    {
      "id": "345",
      "name": "PALCI cultural preservation"
    },
    {
      "id": "456",
      "name": "Coalition for Slavic literature"
    }
  ],
  "people": [
    {
      "xid": "p567",
      "role": "Admin"
    },
    {
      "xid": "p678",
      "role": "`Visionary"
    }
  ],
  "origins": [
    {
      "id": "789",
      "name": "Lehigh"
    },
    {
      "id": "890",
      "name": "NYU"
    }
  ],
  "destinations": [
    {
      "id": "901",
      "name": "CLOCKSS"
    }
  ],
  "tracks": [
    {
      "id": "12",
      "name": "Offsite"
    },
    {
      "id": "123",
      "name": "Reserve"
    },
    {
      "id": "234",
      "name": "Stacks"
    }
  ]
}

HTTP status code 204

No content is returned.

/cyclops/projects/{projectId}/sets get

Sets of objects (books, films, etc.) in this project

get

Return a list of all known sets in this project, with their titles

Request
Response

URI Parameters

projectId: required(string)
The machine-readable identifier of the project

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "An object containing a list of zero or more sets",
  "type": "object",
  "properties": {
    "sets": {
      "description": "The known sets, each with the project that it belongs to",
      "type": "array",
      "items": {
        "type": "object",
        "description": "A set, in the project that it belongs to",
        "properties": {
          "project": {
            "type": "string",
            "description": "The name of the project that the set belongs to"
          },
          "set": {
            "type": "string",
            "description": "The short name of the set, unique within its project"
          },
          "title": {
            "type": "string",
            "description": "The human-readable title of the set"
          }
        },
        "additionalProperties": false,
        "required": [
          "project",
          "set",
          "title"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "sets"
  ]
}

Example:

{
  "sets": [
    {
      "project": "korea_lit",
      "set": "mike",
      "title": "Mike's working set"
    },
    {
      "project": "korea_lit",
      "set": "test",
      "title": "Test data"
    },
    {
      "project": "dinosaurs",
      "set": "uob",
      "title": "Holdings of the University of Bath"
    }
  ]
}

/cyclops/funds get post

Funds that can be associated with a project or assigned to a spectre

get

Return a list of all known funds

post

Create a new fund

Return a list of all known funds

Response

HTTP status code 200

Body

Media type: application/json

Type:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A list of zero or more funds",
  "type": "object",
  "properties": {
    "funds": {
      "description": "The known funds",
      "type": "array",
      "items": {
        "type": "object",
        "description": "A fund",
        "properties": {
          "id": {
            "type": "string",
            "description": "The short machine-readable identifier of the fund"
          },
          "name": {
            "type": "string",
            "description": "The human-readable name of the fund"
          }
        },
        "additionalProperties": false,
        "required": [
          "id",
          "name"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "funds"
  ]
}

Example:

{
  "funds": [
    {
      "id": "coalition_slavic_lit",
      "name": "Coalition for Slavic literature"
    },
    {
      "id": "palci_cultural",
      "name": "PALCI cultural preservation"
    },
    {
      "id": "internet_archive",
      "name": "Internet Archive acquisition"
    }
  ]
}

Create a new fund

Request
Response

Body

Media type: application/json

Type:

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

Example:

{
  "id": "palci_development",
  "name": "PALCI development fund"
}

HTTP status code 204

No content is returned.

/cyclops/funds/{fundId} get put delete

get

Show a single fund in full

put

Alter an existing fund

delete

Drop an existing fund

Show a single fund in full

Request
Response

URI Parameters

fundId: required(string)
The machine-readable identifier of the fund

HTTP status code 200

Body

Media type: application/json

Type:

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

Example:

{
  "id": "palci_development",
  "name": "PALCI development fund"
}

Alter an existing fund

Request
Response

URI Parameters

fundId: required(string)
The machine-readable identifier of the fund

Body

Media type: application/json

Type:

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

Example:

{
  "id": "palci_development",
  "name": "PALCI development fund"
}

HTTP status code 204

No content is returned.

CYCLOPS (CCLP) API version v1

/cyclops

get /cyclops/version

HTTP status code 200

Body

get /cyclops/tags

HTTP status code 200

Body

post /cyclops/tags

Body

HTTP status code 204

get /cyclops/filters

HTTP status code 200

Body

post /cyclops/filters

Body

HTTP status code 204

get /cyclops/sets

HTTP status code 200

Body

post /cyclops/sets

Body

HTTP status code 204

get /cyclops/sets/{setName}

URI Parameters

Query Parameters

HTTP status code 200

Body

delete /cyclops/sets/{setName}

URI Parameters

HTTP status code 204

post /cyclops/sets/{setName}/add

URI Parameters

Body

HTTP status code 204

post /cyclops/sets/{setName}/remove

URI Parameters

Body

HTTP status code 204

post /cyclops/sets/{setName}/tags/{tagName}

URI Parameters

Body

HTTP status code 204

post /cyclops/sets/{setName}/batch

URI Parameters

Body

HTTP status code 204

post /cyclops/sets/{setName}/{recordId}

URI Parameters

Body

HTTP status code 204

get /cyclops/projects

HTTP status code 200

Body

post /cyclops/projects

Body

HTTP status code 204

get /cyclops/projects/{projectId}

URI Parameters

HTTP status code 200

Body

delete /cyclops/projects/{projectId}

URI Parameters

HTTP status code 204

put /cyclops/projects/{projectId}

URI Parameters

Body

HTTP status code 204

get /cyclops/projects/{projectId}/sets

URI Parameters

HTTP status code 200

Body

get /cyclops/funds

HTTP status code 200

Body

post /cyclops/funds

Body

HTTP status code 204

get /cyclops/funds/{fundId}

URI Parameters