Aggregator Settings (v1)

http://localhost/mod-erm-usage

Table of contents

mod-erm-usage API

This documents the API calls that can be made to query and manage aggregator settings

Aggregator Settings

Collection of aggregator-setting items.

GET /aggregator-settings

Get all aggregator settings

GET /aggregator-settings
Query Parameters
  • query: (string)

    A query expressed as a CQL string (see dev.folio.org/reference/glossary#cql) using valid searchable fields. The first example below shows the general form of a full CQL query, but those fields might not be relevant in this context.

    Example:

    (username=="ab*" or personal.firstName=="ab*" or personal.lastName=="ab*") and active=="true" sortby personal.lastName personal.firstName barcode
    
    active=true sortBy username
    
  • orderBy: (string)

    Order by field: field A, field B

  • order: (one of desc, asc - default: desc)

    Order

  • offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)

    Skip over a number of elements by specifying an offset value for the query

    Example:

    0
  • limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)

    Limit the number of elements returned in the response

    Example:

    10
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns a list of aggregator-setting items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "aggregatorSettings": {
      "type": "array",
      "id": "aggregatorsettings",
      "items": {
        "type": "object",
        "$ref": "aggregatorsetting.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "required": [
    "aggregatorSettings",
    "totalRecords"
  ]
}

Example:

{
  "aggregatorSettings": [
    {
      "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
      "label": "ACM Digital Library",
      "serviceType": "My Service",
      "serviceUrl": "www.myaggregator.com",
      "aggregatorConfig": {
        "apiKey": "abc",
        "requestorId": "def",
        "customerId": "ghi",
        "reportRelease": "4"
      },
      "accountConfig": {
        "configType": "Manual",
        "configMail": "ab@counter-stats.com",
        "displayContact": ["Counter Aggregator Contact", "Tel: +49 1234 - 9876"]
      }
    }
  ],
  "totalRecords": 1
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

unable to list aggregator-settings -- malformed parameter 'query', syntax error at column 6

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to list aggregator-settings -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /aggregator-settings

Post new aggregator settings

POST /aggregator-settings
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Aggregator Settings Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "serviceType": {
      "type": "string",
      "description": "Specifies implementation specific for this aggregator."
    },
    "serviceUrl": {
      "type": "string",
      "description": "Aggregator’s service URL to use for harvesting."
    },
    "aggregatorConfig": {
      "type": "object",
      "description": "Additional key/value pairs for aggregator configuration"
    },
    "accountConfig": {
      "type": "object",
      "properties": {
        "configType": {
          "description": "Specifies how the vendor's access parameters are submitted to the aggregator. These parameters are used by the aggregator to login into the vendor in order to fetch the usage data.",
          "type": "string",
          "enum": [
            "Mail",
            "API",
            "Manual"
          ]
        },
        "configMail": {
          "description": "Given if configType == mail",
          "type": "string"
        },
        "displayContact": {
          "description": "Free text info to display to the user with the SUSHI settings in the eUsage app frontend.",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "configType",
        "configMail"
      ]
    },
    "metadata": {
      "description": "Metadata about creation and changes, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "label",
    "serviceType",
    "serviceUrl",
    "accountConfig"
  ],
  "additionalProperties": true
}

Example:

{
  "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
  "label": "ACM Digital Library",
  "serviceType": "My Service",
  "serviceUrl": "www.myaggregator.com",
  "aggregatorConfig": {
    "apiKey": "abc",
    "requestorId": "def",
    "customerId": "ghi",
    "reportRelease": "4"
  },
  "accountConfig": {
    "configType": "Manual",
    "configMail": "ab@counter-stats.com",
    "displayContact": ["Counter Aggregator Contact", "Tel: +49 1234 - 9876"]
  }
}

Response 201

Returns a newly created item, with server-controlled fields like 'id' populated

Headers
  • Location: required (string)

    URI to the created aggregator-setting item

Body

Media type: application/json

Type: any

Example:

{
  "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
  "label": "ACM Digital Library",
  "serviceType": "My Service",
  "serviceUrl": "www.myaggregator.com",
  "aggregatorConfig": {
    "apiKey": "abc",
    "requestorId": "def",
    "customerId": "ghi",
    "reportRelease": "4"
  },
  "accountConfig": {
    "configType": "Manual",
    "configMail": "ab@counter-stats.com",
    "displayContact": ["Counter Aggregator Contact", "Tel: +49 1234 - 9876"]
  }
}

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to add aggregator-setting -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create aggregator-settings -- unauthorized

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "errors": {
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "error.schema"
      }
    },
    "total_records": {
      "type": "integer"
    }
  }
}

Example:

{
  "errors": [
    {
      "message": "may not be null",
      "type": "1",
      "code": "-1",
      "parameters": [
        {
          "key": "moduleTo",
          "value": "null"
        }
      ]
    }
  ]
}

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

GET /aggregator-settings/{id}

Get one aggregator setting identified by id

GET /aggregator-settings/{id}
URI Parameters
  • id: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns item with a given ID

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Aggregator Settings Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "serviceType": {
      "type": "string",
      "description": "Specifies implementation specific for this aggregator."
    },
    "serviceUrl": {
      "type": "string",
      "description": "Aggregator’s service URL to use for harvesting."
    },
    "aggregatorConfig": {
      "type": "object",
      "description": "Additional key/value pairs for aggregator configuration"
    },
    "accountConfig": {
      "type": "object",
      "properties": {
        "configType": {
          "description": "Specifies how the vendor's access parameters are submitted to the aggregator. These parameters are used by the aggregator to login into the vendor in order to fetch the usage data.",
          "type": "string",
          "enum": [
            "Mail",
            "API",
            "Manual"
          ]
        },
        "configMail": {
          "description": "Given if configType == mail",
          "type": "string"
        },
        "displayContact": {
          "description": "Free text info to display to the user with the SUSHI settings in the eUsage app frontend.",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "configType",
        "configMail"
      ]
    },
    "metadata": {
      "description": "Metadata about creation and changes, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "label",
    "serviceType",
    "serviceUrl",
    "accountConfig"
  ],
  "additionalProperties": true
}

Example:

{
  "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
  "label": "ACM Digital Library",
  "serviceType": "My Service",
  "serviceUrl": "www.myaggregator.com",
  "aggregatorConfig": {
    "apiKey": "abc",
    "requestorId": "def",
    "customerId": "ghi",
    "reportRelease": "4"
  },
  "accountConfig": {
    "configType": "Manual",
    "configMail": "ab@counter-stats.com",
    "displayContact": ["Counter Aggregator Contact", "Tel: +49 1234 - 9876"]
  }
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"aggregator-setting not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

DELETE /aggregator-settings/{id}

Delete aggregator setting identified by id

DELETE /aggregator-settings/{id}
URI Parameters
  • id: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

Item deleted successfully

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to delete aggregator-setting -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"aggregator-setting not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

PUT /aggregator-settings/{id}

Put aggregator setting identified by id

PUT /aggregator-settings/{id}
URI Parameters
  • id: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Aggregator Settings Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "serviceType": {
      "type": "string",
      "description": "Specifies implementation specific for this aggregator."
    },
    "serviceUrl": {
      "type": "string",
      "description": "Aggregator’s service URL to use for harvesting."
    },
    "aggregatorConfig": {
      "type": "object",
      "description": "Additional key/value pairs for aggregator configuration"
    },
    "accountConfig": {
      "type": "object",
      "properties": {
        "configType": {
          "description": "Specifies how the vendor's access parameters are submitted to the aggregator. These parameters are used by the aggregator to login into the vendor in order to fetch the usage data.",
          "type": "string",
          "enum": [
            "Mail",
            "API",
            "Manual"
          ]
        },
        "configMail": {
          "description": "Given if configType == mail",
          "type": "string"
        },
        "displayContact": {
          "description": "Free text info to display to the user with the SUSHI settings in the eUsage app frontend.",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "configType",
        "configMail"
      ]
    },
    "metadata": {
      "description": "Metadata about creation and changes, provided by the server (client should not provide)",
      "type": "object",
      "$ref": "../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "required": [
    "label",
    "serviceType",
    "serviceUrl",
    "accountConfig"
  ],
  "additionalProperties": true
}

Example:

{
  "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
  "label": "ACM Digital Library",
  "serviceType": "My Service",
  "serviceUrl": "www.myaggregator.com",
  "aggregatorConfig": {
    "apiKey": "abc",
    "requestorId": "def",
    "customerId": "ghi",
    "reportRelease": "4"
  },
  "accountConfig": {
    "configType": "Manual",
    "configMail": "ab@counter-stats.com",
    "displayContact": ["Counter Aggregator Contact", "Tel: +49 1234 - 9876"]
  }
}

Response 204

Item successfully updated

Response 400

Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response.

Body

Media type: text/plain

Type: any

Example:

"unable to update aggregator-setting -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"aggregator-setting not found"

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator