Usage Data Providers (v1)

http://localhost/mod-erm-usage

mod-erm-usage API
Usage Data Providers

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",
  "properties": {
    "usageDataProviders": {
      "type": "array",
      "id": "udProvidersData",
      "items": {
        "type": "object",
        "$ref": "udprovider.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "required": [
    "usageDataProviders",
    "totalRecords"
  ]
}

Example:

{
  "usageDataProviders": [
    {
      "id": "4c66b956-23a8-4418-aef6-1c35dcdaccd6",
      "label": "Data provider with aggregator",
      "vendorId": "uuid-123456789",
      "platformId": "uuid-123456789",
      "harvestingStart": "2018-01",
      "harvestingStatus": "active",
      "aggregator": {
        "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
        "vendorCode": "ACMDL"
      },
      "reportRelease": 4,
      "requestedReports": [
        "JR1",
        "TR1"
      ],
      "customerId": "12345def",
      "requestorId": "1234abcd",
      "apiKey": "678iuoi",
      "requestorName": "Karla Kolumna",
      "requestorMail": "kolumna@ub.uni-leipzig.de"
    },
    {
      "id": "bf6c9ddc-ff82-40c4-be64-dd2414bdcd72",
      "label": "Data provider without aggregator",
      "vendorId": "uuid-123456789",
      "platformId": "uuid-123456789",
      "harvestingStart": "2018-01",
      "harvestingStatus": "active",
      "serviceType": "Sushi",
      "serviceUrl": "http://myvendor.com",
      "reportRelease": 4,
      "requestedReports": [
        "JR1",
        "TR1"
      ],
      "customerId": "12345def",
      "requestorId": "1234abcd",
      "apiKey": "678iuoi",
      "requestorName": "Karla Kolumna",
      "requestorMail": "kolumna@ub.uni-leipzig.de"
    }
  ],
  "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#",
  "title": "Usage Data Provider Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "vendorId": {
      "type": "string",
      "description": "Id of the the reports content’s vendor, linked via uuid from vendor app."
    },
    "platformId": {
      "type": "string",
      "description": "Id of the reports content’s platform, linked via uuid from ERM app."
    },
    "harvestingStart": {
      "type": "string",
      "format": "date-month"
    },
    "harvestingEnd": {
      "type": "string",
      "format": "date-month"
    },
    "harvestingStatus": {
      "type": "string",
      "enum": [
        "active",
        "inactive",
        "in process",
        "not possible"
      ]
    },
    "aggregator": {
      "type": "object",
      "description": "Defined if statistics are harvested via aggregator",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of aggregator, linking of an aggregator predefined by an admin in the app settings"
        },
        "vendorCode": {
          "type": "string",
          "description": "Code used by the aggregator to identify the vendor (e. g. platform parameter at National Statistic Server)"
        }
      },
      "required": [
        "id"
      ]
    },
    "serviceType": {
      "type": "string",
      "description": "Type of SUSHI service (i.e. SUSHI/SUSHI-Lite) for direct harvesting. If an aggregator is used for harvesting, serviceType is not specified."
    },
    "serviceUrl": {
      "type": "string",
      "description": "Direct SUSHI service URL used by the vendor. If an aggregator is used for harvesting, serviceUrl is not specified, the aggregator’s service URL saved in the settings will be used for harvesting."
    },
    "reportRelease": {
      "type": "integer",
      "description": "Specifies the counter report version."
    },
    "requestedReports": {
      "type": "array",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "customerId": {
      "type": "string"
    },
    "requestorId": {
      "type": "string"
    },
    "apiKey": {
      "type": "string"
    },
    "requestorName": {
      "type": "string"
    },
    "requestorMail": {
      "type": "string"
    },
    "notes": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "$ref": "../raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "../raml-util/schemas/tags.schema"
    }
  },
  "required": [
    "label",
    "vendorId",
    "platformId",
    "harvestingStart",
    "harvestingStatus",
    "reportRelease",
    "requestedReports"
  ],
  "additionalProperties": true
}

Example:

{
  "id": "4c66b956-23a8-4418-aef6-1c35dcdaccd6",
  "label": "Data provider with aggregator",
  "vendorId": "uuid-123456789",
  "platformId": "uuid-123456789",
  "harvestingStart": "2018-01",
  "harvestingStatus": "active",
  "aggregator": {
    "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
    "vendorCode": "ACMDL"
  },
  "reportRelease": 4,
  "requestedReports": [
    "JR1",
    "TR1"
  ],
  "customerId": "12345def",
  "requestorId": "1234abcd",
  "apiKey": "678iuoi",
  "requestorName": "Karla Kolumna",
  "requestorMail": "kolumna@ub.uni-leipzig.de",
  "notes": "New customer ID since 2018-05-01"
}

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": "4c66b956-23a8-4418-aef6-1c35dcdaccd6",
  "label": "Data provider with aggregator",
  "vendorId": "uuid-123456789",
  "platformId": "uuid-123456789",
  "harvestingStart": "2018-01",
  "harvestingStatus": "active",
  "aggregator": {
    "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
    "vendorCode": "ACMDL"
  },
  "reportRelease": 4,
  "requestedReports": [
    "JR1",
    "TR1"
  ],
  "customerId": "12345def",
  "requestorId": "1234abcd",
  "apiKey": "678iuoi",
  "requestorName": "Karla Kolumna",
  "requestorMail": "kolumna@ub.uni-leipzig.de",
  "notes": "New customer ID since 2018-05-01"
}

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#",
  "title": "Usage Data Provider Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "vendorId": {
      "type": "string",
      "description": "Id of the the reports content’s vendor, linked via uuid from vendor app."
    },
    "platformId": {
      "type": "string",
      "description": "Id of the reports content’s platform, linked via uuid from ERM app."
    },
    "harvestingStart": {
      "type": "string",
      "format": "date-month"
    },
    "harvestingEnd": {
      "type": "string",
      "format": "date-month"
    },
    "harvestingStatus": {
      "type": "string",
      "enum": [
        "active",
        "inactive",
        "in process",
        "not possible"
      ]
    },
    "aggregator": {
      "type": "object",
      "description": "Defined if statistics are harvested via aggregator",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of aggregator, linking of an aggregator predefined by an admin in the app settings"
        },
        "vendorCode": {
          "type": "string",
          "description": "Code used by the aggregator to identify the vendor (e. g. platform parameter at National Statistic Server)"
        }
      },
      "required": [
        "id"
      ]
    },
    "serviceType": {
      "type": "string",
      "description": "Type of SUSHI service (i.e. SUSHI/SUSHI-Lite) for direct harvesting. If an aggregator is used for harvesting, serviceType is not specified."
    },
    "serviceUrl": {
      "type": "string",
      "description": "Direct SUSHI service URL used by the vendor. If an aggregator is used for harvesting, serviceUrl is not specified, the aggregator’s service URL saved in the settings will be used for harvesting."
    },
    "reportRelease": {
      "type": "integer",
      "description": "Specifies the counter report version."
    },
    "requestedReports": {
      "type": "array",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "customerId": {
      "type": "string"
    },
    "requestorId": {
      "type": "string"
    },
    "apiKey": {
      "type": "string"
    },
    "requestorName": {
      "type": "string"
    },
    "requestorMail": {
      "type": "string"
    },
    "notes": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "$ref": "../raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "../raml-util/schemas/tags.schema"
    }
  },
  "required": [
    "label",
    "vendorId",
    "platformId",
    "harvestingStart",
    "harvestingStatus",
    "reportRelease",
    "requestedReports"
  ],
  "additionalProperties": true
}

Example:

{
  "id": "4c66b956-23a8-4418-aef6-1c35dcdaccd6",
  "label": "Data provider with aggregator",
  "vendorId": "uuid-123456789",
  "platformId": "uuid-123456789",
  "harvestingStart": "2018-01",
  "harvestingStatus": "active",
  "aggregator": {
    "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
    "vendorCode": "ACMDL"
  },
  "reportRelease": 4,
  "requestedReports": [
    "JR1",
    "TR1"
  ],
  "customerId": "12345def",
  "requestorId": "1234abcd",
  "apiKey": "678iuoi",
  "requestorName": "Karla Kolumna",
  "requestorMail": "kolumna@ub.uni-leipzig.de",
  "notes": "New customer ID since 2018-05-01"
}

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#",
  "title": "Usage Data Provider Schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "vendorId": {
      "type": "string",
      "description": "Id of the the reports content’s vendor, linked via uuid from vendor app."
    },
    "platformId": {
      "type": "string",
      "description": "Id of the reports content’s platform, linked via uuid from ERM app."
    },
    "harvestingStart": {
      "type": "string",
      "format": "date-month"
    },
    "harvestingEnd": {
      "type": "string",
      "format": "date-month"
    },
    "harvestingStatus": {
      "type": "string",
      "enum": [
        "active",
        "inactive",
        "in process",
        "not possible"
      ]
    },
    "aggregator": {
      "type": "object",
      "description": "Defined if statistics are harvested via aggregator",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id of aggregator, linking of an aggregator predefined by an admin in the app settings"
        },
        "vendorCode": {
          "type": "string",
          "description": "Code used by the aggregator to identify the vendor (e. g. platform parameter at National Statistic Server)"
        }
      },
      "required": [
        "id"
      ]
    },
    "serviceType": {
      "type": "string",
      "description": "Type of SUSHI service (i.e. SUSHI/SUSHI-Lite) for direct harvesting. If an aggregator is used for harvesting, serviceType is not specified."
    },
    "serviceUrl": {
      "type": "string",
      "description": "Direct SUSHI service URL used by the vendor. If an aggregator is used for harvesting, serviceUrl is not specified, the aggregator’s service URL saved in the settings will be used for harvesting."
    },
    "reportRelease": {
      "type": "integer",
      "description": "Specifies the counter report version."
    },
    "requestedReports": {
      "type": "array",
      "minItems": 0,
      "items": {
        "type": "string"
      }
    },
    "customerId": {
      "type": "string"
    },
    "requestorId": {
      "type": "string"
    },
    "apiKey": {
      "type": "string"
    },
    "requestorName": {
      "type": "string"
    },
    "requestorMail": {
      "type": "string"
    },
    "notes": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "$ref": "../raml-util/schemas/metadata.schema"
    },
    "tags": {
      "type": "object",
      "$ref": "../raml-util/schemas/tags.schema"
    }
  },
  "required": [
    "label",
    "vendorId",
    "platformId",
    "harvestingStart",
    "harvestingStatus",
    "reportRelease",
    "requestedReports"
  ],
  "additionalProperties": true
}

Example:

{
  "id": "4c66b956-23a8-4418-aef6-1c35dcdaccd6",
  "label": "Data provider with aggregator",
  "vendorId": "uuid-123456789",
  "platformId": "uuid-123456789",
  "harvestingStart": "2018-01",
  "harvestingStatus": "active",
  "aggregator": {
    "id": "4c66b956-23a8-4418-aef6-1c35dcdaccc4",
    "vendorCode": "ACMDL"
  },
  "reportRelease": 4,
  "requestedReports": [
    "JR1",
    "TR1"
  ],
  "customerId": "12345def",
  "requestorId": "1234abcd",
  "apiKey": "678iuoi",
  "requestorName": "Karla Kolumna",
  "requestorMail": "kolumna@ub.uni-leipzig.de",
  "notes": "New customer ID since 2018-05-01"
}

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

Usage Data Providers (v1)

Table of contents

mod-erm-usage API

Usage Data Providers

GET /usage-data-providers

Query Parameters

Response 200

Response 400

Response 401

Response 500

POST /usage-data-providers

Query Parameters

Response 201

Headers

Response 400

Response 401

Response 422

Response 500

GET /usage-data-providers/{id}

URI Parameters

Query Parameters

Response 200

Response 404

Response 500

DELETE /usage-data-providers/{id}

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 500

PUT /usage-data-providers/{id}

URI Parameters

Query Parameters

Response 204

Response 400

Response 404

Response 500