Usage Data Providers (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 usage data providers

Usage Data Providers

Collection of usage-data-provider items.

GET /usage-data-providers

Get all usage data providers

GET /usage-data-providers
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 usage-data-provider items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "List of Usage Data Providers",
  "properties": {
    "usageDataProviders": {
      "type": "array",
      "description": "Entries",
      "id": "udProvidersData",
      "items": {
        "type": "object",
        "$ref": "udprovider.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "required": [
    "usageDataProviders",
    "totalRecords"
  ]
}

Example:

{
  "usageDataProviders": [
    {
      "id": "bf6c9ddc-ff82-40c4-be64-dd2414bdcd73",
      "label": "Data provider with aggregator",
      "harvestingConfig": {
        "harvestingStatus": "active",
        "harvestVia": "aggregator",
        "sushiConfig": {
          "serviceType": "cs41",
          "serviceUrl": "http://myvendor.com"
        },
        "aggregator": {
          "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
          "vendorCode": "ACMDL"
        },
        "reportRelease": 4,
        "requestedReports": [
          "JR1",
          "TR1"
        ],
        "harvestingStart": "2018-01",
        "harvestingEnd": "2018-12"
      },
      "sushiCredentials": {
        "customerId": "12345def",
        "requestorId": "1234abcd",
        "apiKey": "678iuoi",
        "requestorName": "Karla Kolumna",
        "requestorMail": "kolumna@ub.uni-leipzig.de"
      },
      "notes": "This is a note!"
    },
    {
      "id": "bf6c9ddc-ff82-40c4-be64-dd2414bdcd72",
      "label": "Data provider without aggregator",
      "harvestingConfig": {
        "harvestingStatus": "active",
        "harvestVia": "sushi",
        "sushiConfig": {
          "serviceType": "cs41",
          "serviceUrl": "http://myvendor.com"
        },
        "aggregator": {
          "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
          "vendorCode": "ACMDL"
        },
        "reportRelease": 4,
        "requestedReports": [
          "JR1",
          "TR1"
        ],
        "harvestingStart": "2018-01"
      },
      "sushiCredentials": {
        "customerId": "12345def",
        "requestorId": "1234abcd",
        "apiKey": "678iuoi",
        "requestorName": "Karla Kolumna",
        "requestorMail": "kolumna@ub.uni-leipzig.de"
      },
      "notes": "This is a note!"
    }
  ],
  "totalRecords": 2
}

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 usage-data-providers -- 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 usage-data-providers -- 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 /usage-data-providers

Post new usage data providers

POST /usage-data-providers
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#",
  "description": "Usage Data Provider Schema",
  "title": "Usage Data Provider Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "label": {
      "description": "Usage Data Provider name",
      "type": "string"
    },
    "description": {
      "description": "Usage Data Provider description",
      "type": "string"
    },
    "harvestingConfig": {
      "type": "object",
      "description": "Specifies harvesting configuration",
      "properties": {
        "harvestingStatus": {
          "description": "Enables or disables automatic harvesting for this provider",
          "type": "string",
          "enum": [
            "active",
            "inactive"
          ]
        },
        "harvestVia": {
          "type": "string",
          "description": "Specifies how to harvest usage data, from an aggregator or directly from a provider via Sushi.",
          "enum": [
            "aggregator",
            "sushi"
          ]
        },
        "sushiConfig": {
          "description": "SUSHI service properties",
          "type": "object",
          "properties": {
            "serviceType": {
              "type": "string",
              "description": "Type of SUSHI service (i.e. cs41 for Counter-Sushi 4.1) for direct harvesting."
            },
            "serviceUrl": {
              "type": "string",
              "description": "Direct SUSHI service URL to access provider's SUSHI service."
            }
          },
          "required": [
            "serviceType",
            "serviceUrl"
          ]
        },
        "aggregator": {
          "type": "object",
          "description": "Links to aggregator, if statistic shall be harvested via aggregator",
          "properties": {
            "id": {
              "type": "string",
              "description": "Id of aggregator, linking of an aggregator predefined by an admin in the app settings"
            },
            "name": {
              "type": "string",
              "description": "Name of the linked aggregator"
            },
            "vendorCode": {
              "type": "string",
              "description": "Code used by the aggregator to identify the vendor (e. g. platform parameter at National Statistic Server)"
            }
          },
          "required": [
            "id"
          ]
        },
        "reportRelease": {
          "type": "integer",
          "description": "Specifies the counter report version."
        },
        "requestedReports": {
          "description": "Report types that are harvested",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "string"
          }
        },
        "harvestingStart": {
          "description": "First month getting harvested",
          "type": "string",
          "format": "date-month"
        },
        "harvestingEnd": {
          "description": "Last month getting harvested",
          "type": "string",
          "format": "date-month"
        }
      },
      "required": [
        "harvestingStatus",
        "useAggregator",
        "reportRelease",
        "requestedReports",
        "harvestingStart"
      ]
    },
    "sushiCredentials": {
      "type": "object",
      "description": "Defines credentials to access SUSHI service of usage data provider",
      "properties": {
        "customerId": {
          "description": "Customer identifier",
          "type": "string"
        },
        "requestorId": {
          "description": "Requestor identifier",
          "type": "string"
        },
        "apiKey": {
          "description": "API Key",
          "type": "string"
        },
        "platform": {
          "description": "Name of the Platform the usage is being requested for",
          "type": "string"
        },
        "requestorName": {
          "description": "Requestor name",
          "type": "string"
        },
        "requestorMail": {
          "description": "Requestor mail",
          "type": "string"
        }
      },
      "required": [
        "customerId"
      ]
    },
    "latestReport": {
      "description": "Newest report available for provider",
      "type": "string"
    },
    "earliestReport": {
      "description": "Oldest report available for provider",
      "type": "string"
    },
    "notes": {
      "description": "Notes for provider",
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "$ref": "../raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "../raml-util/schemas/tags.schema"
    }
  },
  "required": [
    "label",
    "harvestingConfig"
  ],
  "additionalProperties": true
}

Example:

{
  "id": "bf6c9ddc-ff82-40c4-be64-dd2414bdcd72",
  "label": "Data provider without aggregator",
  "harvestingConfig": {
    "harvestingStatus": "active",
    "harvestVia": "sushi",
    "sushiConfig": {
      "serviceType": "cs41",
      "serviceUrl": "http://myvendor.com"
    },
    "reportRelease": 4,
    "requestedReports": [
      "JR1",
      "TR1"
    ],
    "harvestingStart": "2018-01",
    "harvestingEnd": "2018-12"
  },
  "sushiCredentials": {
    "customerId": "12345def",
    "requestorId": "1234abcd",
    "apiKey": "678iuoi",
    "requestorName": "Karla Kolumna",
    "requestorMail": "kolumna@ub.uni-leipzig.de"
  },
  "earliestReport": "2017-01",
  "latestReport": "2017-12",
  "notes": "This is a note!"
}

Response 201

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

Headers
  • Location: required (string)

    URI to the created usage-data-provider item

Body

Media type: application/json

Type: any

Example:

{
  "id": "bf6c9ddc-ff82-40c4-be64-dd2414bdcd72",
  "label": "Data provider without aggregator",
  "harvestingConfig": {
    "harvestingStatus": "active",
    "harvestVia": "sushi",
    "sushiConfig": {
      "serviceType": "cs41",
      "serviceUrl": "http://myvendor.com"
    },
    "reportRelease": 4,
    "requestedReports": [
      "JR1",
      "TR1"
    ],
    "harvestingStart": "2018-01",
    "harvestingEnd": "2018-12"
  },
  "sushiCredentials": {
    "customerId": "12345def",
    "requestorId": "1234abcd",
    "apiKey": "678iuoi",
    "requestorName": "Karla Kolumna",
    "requestorMail": "kolumna@ub.uni-leipzig.de"
  },
  "earliestReport": "2017-01",
  "latestReport": "2017-12",
  "notes": "This is a note!"
}

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 usage-data-provider -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create usage-data-providers -- 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 /usage-data-providers/{id}

Get one usage data provider identified by id

GET /usage-data-providers/{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#",
  "description": "Usage Data Provider Schema",
  "title": "Usage Data Provider Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "label": {
      "description": "Usage Data Provider name",
      "type": "string"
    },
    "description": {
      "description": "Usage Data Provider description",
      "type": "string"
    },
    "harvestingConfig": {
      "type": "object",
      "description": "Specifies harvesting configuration",
      "properties": {
        "harvestingStatus": {
          "description": "Enables or disables automatic harvesting for this provider",
          "type": "string",
          "enum": [
            "active",
            "inactive"
          ]
        },
        "harvestVia": {
          "type": "string",
          "description": "Specifies how to harvest usage data, from an aggregator or directly from a provider via Sushi.",
          "enum": [
            "aggregator",
            "sushi"
          ]
        },
        "sushiConfig": {
          "description": "SUSHI service properties",
          "type": "object",
          "properties": {
            "serviceType": {
              "type": "string",
              "description": "Type of SUSHI service (i.e. cs41 for Counter-Sushi 4.1) for direct harvesting."
            },
            "serviceUrl": {
              "type": "string",
              "description": "Direct SUSHI service URL to access provider's SUSHI service."
            }
          },
          "required": [
            "serviceType",
            "serviceUrl"
          ]
        },
        "aggregator": {
          "type": "object",
          "description": "Links to aggregator, if statistic shall be harvested via aggregator",
          "properties": {
            "id": {
              "type": "string",
              "description": "Id of aggregator, linking of an aggregator predefined by an admin in the app settings"
            },
            "name": {
              "type": "string",
              "description": "Name of the linked aggregator"
            },
            "vendorCode": {
              "type": "string",
              "description": "Code used by the aggregator to identify the vendor (e. g. platform parameter at National Statistic Server)"
            }
          },
          "required": [
            "id"
          ]
        },
        "reportRelease": {
          "type": "integer",
          "description": "Specifies the counter report version."
        },
        "requestedReports": {
          "description": "Report types that are harvested",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "string"
          }
        },
        "harvestingStart": {
          "description": "First month getting harvested",
          "type": "string",
          "format": "date-month"
        },
        "harvestingEnd": {
          "description": "Last month getting harvested",
          "type": "string",
          "format": "date-month"
        }
      },
      "required": [
        "harvestingStatus",
        "useAggregator",
        "reportRelease",
        "requestedReports",
        "harvestingStart"
      ]
    },
    "sushiCredentials": {
      "type": "object",
      "description": "Defines credentials to access SUSHI service of usage data provider",
      "properties": {
        "customerId": {
          "description": "Customer identifier",
          "type": "string"
        },
        "requestorId": {
          "description": "Requestor identifier",
          "type": "string"
        },
        "apiKey": {
          "description": "API Key",
          "type": "string"
        },
        "platform": {
          "description": "Name of the Platform the usage is being requested for",
          "type": "string"
        },
        "requestorName": {
          "description": "Requestor name",
          "type": "string"
        },
        "requestorMail": {
          "description": "Requestor mail",
          "type": "string"
        }
      },
      "required": [
        "customerId"
      ]
    },
    "latestReport": {
      "description": "Newest report available for provider",
      "type": "string"
    },
    "earliestReport": {
      "description": "Oldest report available for provider",
      "type": "string"
    },
    "notes": {
      "description": "Notes for provider",
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "$ref": "../raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "../raml-util/schemas/tags.schema"
    }
  },
  "required": [
    "label",
    "harvestingConfig"
  ],
  "additionalProperties": true
}

Example:

{
  "id": "bf6c9ddc-ff82-40c4-be64-dd2414bdcd72",
  "label": "Data provider without aggregator",
  "harvestingConfig": {
    "harvestingStatus": "active",
    "harvestVia": "sushi",
    "sushiConfig": {
      "serviceType": "cs41",
      "serviceUrl": "http://myvendor.com"
    },
    "reportRelease": 4,
    "requestedReports": [
      "JR1",
      "TR1"
    ],
    "harvestingStart": "2018-01",
    "harvestingEnd": "2018-12"
  },
  "sushiCredentials": {
    "customerId": "12345def",
    "requestorId": "1234abcd",
    "apiKey": "678iuoi",
    "requestorName": "Karla Kolumna",
    "requestorMail": "kolumna@ub.uni-leipzig.de"
  },
  "earliestReport": "2017-01",
  "latestReport": "2017-12",
  "notes": "This is a note!"
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"usage-data-provider 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 /usage-data-providers/{id}

Delete an usage data provider identified by id

DELETE /usage-data-providers/{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 usage-data-provider -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"usage-data-provider 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 /usage-data-providers/{id}

Put an usage data provider identified by id

PUT /usage-data-providers/{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#",
  "description": "Usage Data Provider Schema",
  "title": "Usage Data Provider Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "label": {
      "description": "Usage Data Provider name",
      "type": "string"
    },
    "description": {
      "description": "Usage Data Provider description",
      "type": "string"
    },
    "harvestingConfig": {
      "type": "object",
      "description": "Specifies harvesting configuration",
      "properties": {
        "harvestingStatus": {
          "description": "Enables or disables automatic harvesting for this provider",
          "type": "string",
          "enum": [
            "active",
            "inactive"
          ]
        },
        "harvestVia": {
          "type": "string",
          "description": "Specifies how to harvest usage data, from an aggregator or directly from a provider via Sushi.",
          "enum": [
            "aggregator",
            "sushi"
          ]
        },
        "sushiConfig": {
          "description": "SUSHI service properties",
          "type": "object",
          "properties": {
            "serviceType": {
              "type": "string",
              "description": "Type of SUSHI service (i.e. cs41 for Counter-Sushi 4.1) for direct harvesting."
            },
            "serviceUrl": {
              "type": "string",
              "description": "Direct SUSHI service URL to access provider's SUSHI service."
            }
          },
          "required": [
            "serviceType",
            "serviceUrl"
          ]
        },
        "aggregator": {
          "type": "object",
          "description": "Links to aggregator, if statistic shall be harvested via aggregator",
          "properties": {
            "id": {
              "type": "string",
              "description": "Id of aggregator, linking of an aggregator predefined by an admin in the app settings"
            },
            "name": {
              "type": "string",
              "description": "Name of the linked aggregator"
            },
            "vendorCode": {
              "type": "string",
              "description": "Code used by the aggregator to identify the vendor (e. g. platform parameter at National Statistic Server)"
            }
          },
          "required": [
            "id"
          ]
        },
        "reportRelease": {
          "type": "integer",
          "description": "Specifies the counter report version."
        },
        "requestedReports": {
          "description": "Report types that are harvested",
          "type": "array",
          "minItems": 0,
          "items": {
            "type": "string"
          }
        },
        "harvestingStart": {
          "description": "First month getting harvested",
          "type": "string",
          "format": "date-month"
        },
        "harvestingEnd": {
          "description": "Last month getting harvested",
          "type": "string",
          "format": "date-month"
        }
      },
      "required": [
        "harvestingStatus",
        "useAggregator",
        "reportRelease",
        "requestedReports",
        "harvestingStart"
      ]
    },
    "sushiCredentials": {
      "type": "object",
      "description": "Defines credentials to access SUSHI service of usage data provider",
      "properties": {
        "customerId": {
          "description": "Customer identifier",
          "type": "string"
        },
        "requestorId": {
          "description": "Requestor identifier",
          "type": "string"
        },
        "apiKey": {
          "description": "API Key",
          "type": "string"
        },
        "platform": {
          "description": "Name of the Platform the usage is being requested for",
          "type": "string"
        },
        "requestorName": {
          "description": "Requestor name",
          "type": "string"
        },
        "requestorMail": {
          "description": "Requestor mail",
          "type": "string"
        }
      },
      "required": [
        "customerId"
      ]
    },
    "latestReport": {
      "description": "Newest report available for provider",
      "type": "string"
    },
    "earliestReport": {
      "description": "Oldest report available for provider",
      "type": "string"
    },
    "notes": {
      "description": "Notes for provider",
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "$ref": "../raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "../raml-util/schemas/tags.schema"
    }
  },
  "required": [
    "label",
    "harvestingConfig"
  ],
  "additionalProperties": true
}

Example:

{
  "id": "bf6c9ddc-ff82-40c4-be64-dd2414bdcd72",
  "label": "Data provider without aggregator",
  "harvestingConfig": {
    "harvestingStatus": "active",
    "harvestVia": "sushi",
    "sushiConfig": {
      "serviceType": "cs41",
      "serviceUrl": "http://myvendor.com"
    },
    "reportRelease": 4,
    "requestedReports": [
      "JR1",
      "TR1"
    ],
    "harvestingStart": "2018-01",
    "harvestingEnd": "2018-12"
  },
  "sushiCredentials": {
    "customerId": "12345def",
    "requestorId": "1234abcd",
    "apiKey": "678iuoi",
    "requestorName": "Karla Kolumna",
    "requestorMail": "kolumna@ub.uni-leipzig.de"
  },
  "earliestReport": "2017-01",
  "latestReport": "2017-12",
  "notes": "This is a note!"
}

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 usage-data-provider -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"usage-data-provider 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