Pub-sub (v0.1)

http://localhost

Table of contents

PubSub API

API for event-driven approach

/pubsub

POST /pubsub/event-types

Create new event type

POST /pubsub/event-types
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": "Event Descriptor data model",
  "javaType": "org.folio.rest.jaxrs.model.EventDescriptor",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "eventType": {
      "description": "Unique Event type, human-readable String, not UUID",
      "type": "string"
    },
    "description" : {
      "description": "Detailed description of the event type",
      "type": "string"
    },
    "eventTTL": {
      "description": "Default time-to-live (TTL) for events of this type in minutes",
      "type": "integer"
    },
    "signed": {
      "description": "Indicated whether all events of this event type must be digitally signed by the publisher",
      "type": "boolean",
      "default": false
    }
  },
  "required": [
    "eventType",
    "eventTTL"
  ]
}

Example:

{
  "eventType": "CREATED_SRS_MARC_BIB_RECORD_WITH_ORDER_DATA",
  "description": "Created SRS Marc Bibliographic Record with order data in 9xx fields",
  "eventTTL": 1,
  "signed": false
}

Response 201

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

Headers
  • Location: required (string)

    URI to the created event-type item

Body

Media type: application/json

Type: any

Example:

{
  "eventType": "CREATED_SRS_MARC_BIB_RECORD_WITH_ORDER_DATA",
  "description": "Created SRS Marc Bibliographic Record with order data in 9xx fields",
  "eventTTL": 1,
  "signed": false
}

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 event-type -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create event-types -- unauthorized

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "error.schema"
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "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 /pubsub/event-types

Get a list of evet type descriptors

GET /pubsub/event-types
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 200

Returns a list of event-type items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Collection of Event Descriptors",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "eventDescriptors": {
      "description": "List of Event Descriptors",
      "type": "array",
      "id": "eventDescriptorsList",
      "items": {
        "type": "object",
        "$ref": "./eventDescriptor.json"
      }
    },
    "totalRecords": {
      "description": "Total number of Event Descriptors",
      "type": "integer"
    }
  },
  "required": [
    "eventDescriptors",
    "totalRecords"
  ]
}

Example:

{
  "eventDescriptors": [
    {
      "eventType": "CREATED_SRS_MARC_BIB_RECORD_WITH_ORDER_DATA",
      "description": "Created SRS Marc Bibliographic Record with order data in 9xx fields",
      "eventTTL": 1,
      "signed": false
    }
  ],
  "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 event-types -- 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 event-types -- unauthorized

Response 500

Internal server error, e.g. due to misconfiguration

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

PUT /pubsub/event-types/{eventTypeName}

Update event-type item with given {event-typeId}

PUT /pubsub/event-types/{eventTypeName}
URI Parameters
  • eventTypeName: 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": "Event Descriptor data model",
  "javaType": "org.folio.rest.jaxrs.model.EventDescriptor",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "eventType": {
      "description": "Unique Event type, human-readable String, not UUID",
      "type": "string"
    },
    "description" : {
      "description": "Detailed description of the event type",
      "type": "string"
    },
    "eventTTL": {
      "description": "Default time-to-live (TTL) for events of this type in minutes",
      "type": "integer"
    },
    "signed": {
      "description": "Indicated whether all events of this event type must be digitally signed by the publisher",
      "type": "boolean",
      "default": false
    }
  },
  "required": [
    "eventType",
    "eventTTL"
  ]
}

Example:

{
  "eventType": "CREATED_SRS_MARC_BIB_RECORD_WITH_ORDER_DATA",
  "description": "Created SRS Marc Bibliographic Record with order data in 9xx fields",
  "eventTTL": 1,
  "signed": false
}

Response 200

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Event Descriptor data model",
  "javaType": "org.folio.rest.jaxrs.model.EventDescriptor",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "eventType": {
      "description": "Unique Event type, human-readable String, not UUID",
      "type": "string"
    },
    "description" : {
      "description": "Detailed description of the event type",
      "type": "string"
    },
    "eventTTL": {
      "description": "Default time-to-live (TTL) for events of this type in minutes",
      "type": "integer"
    },
    "signed": {
      "description": "Indicated whether all events of this event type must be digitally signed by the publisher",
      "type": "boolean",
      "default": false
    }
  },
  "required": [
    "eventType",
    "eventTTL"
  ]
}

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 event-type -- malformed JSON at 13:4"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"event-type not found"

Response 422

Validation errors

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A set of errors",
  "type": "object",
  "properties": {
    "errors": {
      "description": "List of errors",
      "id": "errors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "error.schema"
      }
    },
    "total_records": {
      "description": "Total number of errors",
      "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

DELETE /pubsub/event-types/{eventTypeName}

Delete event-type item with given {event-typeId}

DELETE /pubsub/event-types/{eventTypeName}
URI Parameters
  • eventTypeName: 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 event-type -- constraint violation"

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"event-type 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

GET /pubsub/event-types/{eventTypeName}

Retrieve event-type item with given {event-typeId}

GET /pubsub/event-types/{eventTypeName}
URI Parameters
  • eventTypeName: 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": "Event Descriptor data model",
  "javaType": "org.folio.rest.jaxrs.model.EventDescriptor",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "eventType": {
      "description": "Unique Event type, human-readable String, not UUID",
      "type": "string"
    },
    "description" : {
      "description": "Detailed description of the event type",
      "type": "string"
    },
    "eventTTL": {
      "description": "Default time-to-live (TTL) for events of this type in minutes",
      "type": "integer"
    },
    "signed": {
      "description": "Indicated whether all events of this event type must be digitally signed by the publisher",
      "type": "boolean",
      "default": false
    }
  },
  "required": [
    "eventType",
    "eventTTL"
  ]
}

Example:

{
  "eventType": "CREATED_SRS_MARC_BIB_RECORD_WITH_ORDER_DATA",
  "description": "Created SRS Marc Bibliographic Record with order data in 9xx fields",
  "eventTTL": 1,
  "signed": false
}

Response 404

Item with a given ID not found

Body

Media type: text/plain

Type: any

Example:

"event-type 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

GET /pubsub/event-types/{eventTypeName}/publishers

API to retrieve registered Publishers

GET /pubsub/event-types/{eventTypeName}/publishers
URI Parameters
  • eventTypeName: required (string)

Response 200

Body

Media type: application/json

DELETE /pubsub/event-types/{eventTypeName}/publishers

Remove publisher declaration for certain event type

DELETE /pubsub/event-types/{eventTypeName}/publishers
URI Parameters
  • eventTypeName: required (string)
Query Parameters
  • moduleId: required (string)

    Publisher module name and version

    Example:

    mod-pubsub-1.0.0

Response 204

GET /pubsub/event-types/{eventTypeName}/subscribers

API to retrieve registered Subscribers

GET /pubsub/event-types/{eventTypeName}/subscribers
URI Parameters
  • eventTypeName: required (string)

Response 200

Body

Media type: application/json

DELETE /pubsub/event-types/{eventTypeName}/subscribers

API to remove Subscriber declaration for certain event type

DELETE /pubsub/event-types/{eventTypeName}/subscribers
URI Parameters
  • eventTypeName: required (string)
Query Parameters
  • moduleId: required (string)

    Subscriber module name and version

    Example:

    mod-pubsub-1.0.0

Response 204

POST /pubsub/event-types/declare/publisher

Declare a publisher for a set of event types

POST /pubsub/event-types/declare/publisher
Body

Media type: application/json

Response 201

Response 400

Body

Media type: application/json

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /pubsub/event-types/declare/subscriber

POST /pubsub/event-types/declare/subscriber
Body

Media type: application/json

Response 201

Response 400

Body

Media type: application/json

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /pubsub/history

Get activity history

GET /pubsub/history
Query Parameters
  • startDate: required (string - pattern: \d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d(?:\.\d+)?Z?)

    start date of the period of time for which audit messages are required

    Example:

    2019-09-20T12:00:00
  • endDate: required (string - pattern: \d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d(?:\.\d+)?Z?)

    end date of the period of time for which audit messages are required

    Example:

    2019-09-27T12:00:00
  • eventId: (string)

    eventId by which audit messages should be filtered

  • eventType: (string)

    eventType by which audit messages should be filtered

  • correlationId: (string)

    correlationId by which audit messages should be filtered

Response 200

Body

Media type: application/json

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

Bad request

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

GET /pubsub/audit-messages/{eventId}/payload

Get audit message payload by event id

GET /pubsub/audit-messages/{eventId}/payload
URI Parameters
  • eventId: required (string)

Response 200

Body

Media type: application/json

Response 404

Not found

Body

Media type: text/plain

Type: any

Example:

Not found

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error

POST /pubsub/publish

POST /pubsub/publish
Body

Media type: application/json

Response 204

Response 400

Body

Media type: application/json

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error