Calendar (v1)

https://github.com/folio-org/mod-calendar

Table of contents

mod-calendar API

This module provides a backend for the calendar functionalities

/calendar

GET /calendar/periods

List actual opening hours including exceptions for custom date range. Mainly used by calendar display and provides opening information for loan rules. The response contains only the openings closed times are not included.

GET /calendar/periods
Query Parameters
  • servicePointId: (string)

    Filter for service point. In case of parameter absence all service point will be included in response.

  • startDate: (string)

    Filter for start date (ISO 8601 date format). The parameter is inclusive.

    Example:

    2018-05-01
  • endDate: (string)

    Filter for end date (ISO 8601 date format). The parameter is inclusive.

    Example:

    2018-05-31
  • includeClosedDays: (boolean - default: true)

    In case of true all days will have value even if it is closing time or not

  • actualOpening: (boolean - default: true)

    In case of true exceptional openings are overriding regular opening and in this case regular opening is not included in the response

  • 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 period items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Opening hours collection",
  "type": "object",
  "description": "List actual opening hours",
  "properties": {
    "openingPeriods": {
      "type": "array",
      "description" : "Opening sor a specific date",
      "items": {
        "type": "object",
        "$ref": "OpeningHours.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "openingPeriods",
    "totalRecords"
  ]
}

Example:

{
  "openingPeriods": [
    {
      "openingDay": {
        "openingHour": [
          {
            "startTime": "10:00",
            "endTime": "12:00"
          },
          {
            "startTime": "14:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true,
        "exceptional": false
      },
      "date": "2018-10-01T00:00:00.000+00:00"
    },
    {
      "openingDay": {
        "openingHour": [
          {
            "startTime": "10:00",
            "endTime": "12:00"
          },
          {
            "startTime": "14:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true,
        "exceptional": false
      },
      "date": "2018-10-08T00:00:00.000+00:00"
    },
    {
      "openingDay": {
        "openingHour": [
          {
            "startTime": "10:00",
            "endTime": "12:00"
          },
          {
            "startTime": "14:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true,
        "exceptional": false
      },
      "date": "2018-10-15T00:00:00.000+00:00"
    },
    {
      "openingDay": {
        "openingHour": [
          {
            "startTime": "10:00",
            "endTime": "12:00"
          },
          {
            "startTime": "14:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true,
        "exceptional": false
      },
      "date": "2018-10-22T00:00:00.000+00:00"
    },
    {
      "openingDay": {
        "openingHour": [
          {
            "startTime": "10:00",
            "endTime": "12:00"
          },
          {
            "startTime": "14:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true,
        "exceptional": false
      },
      "date": "2018-10-29T01:00:00.000+00:00"
    },
    {
      "openingDay": {
        "openingHour": [
          {
            "startTime": "10:00",
            "endTime": "12:00"
          },
          {
            "startTime": "14:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true,
        "exceptional": false
      },
      "date": "2018-11-05T01:00:00.000+00:00"
    },
    {
      "openingDay": {
        "openingHour": [
          {
            "startTime": "10:00",
            "endTime": "12:00"
          },
          {
            "startTime": "14:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true,
        "exceptional": false
      },
      "date": "2018-11-12T01:00:00.000+00:00"
    },
    {
      "openingDay": {
        "openingHour": [
          {
            "startTime": "10:00",
            "endTime": "12:00"
          },
          {
            "startTime": "14:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true,
        "exceptional": false
      },
      "date": "2018-11-19T01:00:00.000+00:00"
    },
    {
      "openingDay": {
        "openingHour": [
          {
            "startTime": "10:00",
            "endTime": "12:00"
          },
          {
            "startTime": "14:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true,
        "exceptional": false
      },
      "date": "2018-11-26T01:00:00.000+00:00"
    },
    {
      "openingDay": {
        "openingHour": [
          {
            "startTime": "10:00",
            "endTime": "12:00"
          },
          {
            "startTime": "14:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true,
        "exceptional": true
      },
      "date": "2019-08-01T00:00:00.000+00:00"
    }
  ],
  "totalRecords": 40
}

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 periods -- malformed parameter 'query', syntax error at column 6

Response 404

Not found. There is no service point with the given ID

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

GET /calendar/periods/{servicePointId}/period

List library hours period. The default response contains the period names and its dates.

GET /calendar/periods/{servicePointId}/period
URI Parameters
  • servicePointId: required (string)
Query Parameters
  • withOpeningDays: (boolean - default: false)

    Include opening days in response.

  • showPast: (boolean - default: false)

    Include past openings in response.

  • showExceptional: (boolean - default: false)

    Filter for exceptional library hours periods.

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

    Requested language. Optional. [lang=en]

Response 200

Returns a list of period items

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Opening collection",
  "type": "object",
  "description" : "List of opening periods",
  "properties": {
    "openingPeriods": {
      "type": "array",
      "description" : "Opening period",
      "id": "Openings",
      "items": {
        "type": "object",
        "$ref": "Opening.json"
      }
    },
    "totalRecords": {
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "required": [
    "openingPeriods",
    "totalRecords"
  ]
}

Example:

{
  "openingPeriods": [
    {
      "id": "fa9927e8-5f79-498e-94ea-8b5b474795c8",
      "servicePointId": "1",
      "name": "test1",
      "startDate": "2018-06-01T00:00:00.000+00:00",
      "endDate": "2018-08-01T00:00:00.000+00:00",
      "openingDays": [
        {
          "weekdays": {
            "day": "MONDAY"
          },
          "openingDay": {
            "openingHour": [
              {
                "startTime": "05:00",
                "endTime": "11:00"
              },
              {
                "startTime": "14:00",
                "endTime": "18:00"
              }
            ],
            "allDay": false,
            "open": true
          }
        }
      ]
    },
    {
      "id": "ha9927e8-5f79-498e-94ea-8b5b474795c8",
      "servicePointId": "1",
      "name": "test2",
      "startDate": "2018-09-01T00:00:00.000+00:00",
      "endDate": "2018-10-01T00:00:00.000+00:00",
      "openingDays": [
        {
          "weekdays": {
            "day": "THURSDAY"
          },
          "openingDay": {
            "openingHour": [
              {
                "startTime": "09:00",
                "endTime": "12:00"
              },
              {
                "startTime": "13:00",
                "endTime": "17:00"
              }
            ],
            "allDay": false,
            "open": true
          }
        }
      ]
    }
  ],
  "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 period -- 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 period -- unauthorized

Response 404

Not found. There is no service point with the given ID

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

POST /calendar/periods/{servicePointId}/period

Saves the new library period

POST /calendar/periods/{servicePointId}/period
URI Parameters
  • servicePointId: 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": "Opening",
  "type": "object",
  "description": "Descriptor an opening period.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Period's internal id."
    },
    "servicePointId": {
      "type": "string",
      "description": "Service point ID."
    },
    "name": {
      "type": "string",
      "description": "Name of the period"
    },
    "startDate": {
      "type": "string",
      "format": "date-time",
      "description": "Start date of the period."
    },
    "endDate": {
      "type": "string",
      "format": "date-time",
      "description": "End date of the period."
    },
    "openingDays": {
      "type": "array",
      "description": "List opening hours within the period.",
      "items": {
        "type": "object",
        "$ref": "OpeningDayIncludeWeekdays.json"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "startDate"
  ]
}

Example:

{
  "id": "ha9927e8-5f79-498e-94ea-8b5b474795c8",
  "servicePointId": "1",
  "name": "test2",
  "startDate": "2018-09-01T00:00:00.000+00:00",
  "endDate": "2018-10-01T00:00:00.000+00:00",
  "openingDays": [
    {
      "weekdays": {
        "day": "THURSDAY"
      },
      "openingDay": {
        "openingHour": [
          {
            "startTime": "09:00",
            "endTime": "12:00"
          },
          {
            "startTime": "13:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true
      }
    }
  ]
}

Response 201

Returns with the created period

Headers
  • Location: required (string)

    URI to the created period item

Body

Media type: application/json

Type: json

Content:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Opening",
  "type": "object",
  "description": "Descriptor an opening period.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Period's internal id."
    },
    "servicePointId": {
      "type": "string",
      "description": "Service point ID."
    },
    "name": {
      "type": "string",
      "description": "Name of the period"
    },
    "startDate": {
      "type": "string",
      "format": "date-time",
      "description": "Start date of the period."
    },
    "endDate": {
      "type": "string",
      "format": "date-time",
      "description": "End date of the period."
    },
    "openingDays": {
      "type": "array",
      "description": "List opening hours within the period.",
      "items": {
        "type": "object",
        "$ref": "OpeningDayIncludeWeekdays.json"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "startDate"
  ]
}

Example:

{
  "id": "ha9927e8-5f79-498e-94ea-8b5b474795c8",
  "servicePointId": "1",
  "name": "test2",
  "startDate": "2018-09-01T00:00:00.000+00:00",
  "endDate": "2018-10-01T00:00:00.000+00:00",
  "openingDays": [
    {
      "weekdays": {
        "day": "THURSDAY"
      },
      "openingDay": {
        "openingHour": [
          {
            "startTime": "09:00",
            "endTime": "12:00"
          },
          {
            "startTime": "13:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true
      }
    }
  ]
}

Response 400

Bad request

Body

Media type: text/plain

Type: any

Example:

"unable to add period -- malformed JSON at 13:3"

Response 401

Not authorized to perform requested action

Body

Media type: text/plain

Type: any

Example:

unable to create period -- 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": {
      "type": "integer"
    }
  }
}

Example:

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

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

Internal server error, contact administrator

GET /calendar/periods/{servicePointId}/period/{periodId}

List opening hours for given periodId.

GET /calendar/periods/{servicePointId}/period/{periodId}
URI Parameters
  • servicePointId: required (string)
  • periodId: 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": "Opening",
  "type": "object",
  "description": "Descriptor an opening period.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Period's internal id."
    },
    "servicePointId": {
      "type": "string",
      "description": "Service point ID."
    },
    "name": {
      "type": "string",
      "description": "Name of the period"
    },
    "startDate": {
      "type": "string",
      "format": "date-time",
      "description": "Start date of the period."
    },
    "endDate": {
      "type": "string",
      "format": "date-time",
      "description": "End date of the period."
    },
    "openingDays": {
      "type": "array",
      "description": "List opening hours within the period.",
      "items": {
        "type": "object",
        "$ref": "OpeningDayIncludeWeekdays.json"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "startDate"
  ]
}

Example:

{
  "id": "ha9927e8-5f79-498e-94ea-8b5b474795c8",
  "servicePointId": "1",
  "name": "test2",
  "startDate": "2018-09-01T00:00:00.000+00:00",
  "endDate": "2018-10-01T00:00:00.000+00:00",
  "openingDays": [
    {
      "weekdays": {
        "day": "THURSDAY"
      },
      "openingDay": {
        "openingHour": [
          {
            "startTime": "09:00",
            "endTime": "12:00"
          },
          {
            "startTime": "13:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true
      }
    }
  ]
}

Response 404

Library hours period or service point with the given ID is not found

Body

Media type: text/plain

Type: any

Example:

"period not found"

Response 500

Internal server error

Body

Media type: text/plain

Type: any

Example:

internal server error, contact administrator

DELETE /calendar/periods/{servicePointId}/period/{periodId}

Delete Opening hours by Id

DELETE /calendar/periods/{servicePointId}/period/{periodId}
URI Parameters
  • servicePointId: required (string)
  • periodId: required (string)
Query Parameters
  • lang: (string - default: en - pattern: [a-zA-Z]{2})

    Requested language. Optional. [lang=en]

Response 204

Library hours period was 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 period -- constraint violation"

Response 404

Library hours period or service point with the given ID is not found

Body

Media type: text/plain

Type: any

Example:

"period 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 /calendar/periods/{servicePointId}/period/{periodId}

Update library period by periodId

PUT /calendar/periods/{servicePointId}/period/{periodId}
URI Parameters
  • servicePointId: required (string)
  • periodId: 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": "Opening",
  "type": "object",
  "description": "Descriptor an opening period.",
  "properties": {
    "id": {
      "type": "string",
      "description": "Period's internal id."
    },
    "servicePointId": {
      "type": "string",
      "description": "Service point ID."
    },
    "name": {
      "type": "string",
      "description": "Name of the period"
    },
    "startDate": {
      "type": "string",
      "format": "date-time",
      "description": "Start date of the period."
    },
    "endDate": {
      "type": "string",
      "format": "date-time",
      "description": "End date of the period."
    },
    "openingDays": {
      "type": "array",
      "description": "List opening hours within the period.",
      "items": {
        "type": "object",
        "$ref": "OpeningDayIncludeWeekdays.json"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "startDate"
  ]
}

Example:

{
  "id": "ha9927e8-5f79-498e-94ea-8b5b474795c8",
  "servicePointId": "1",
  "name": "test2",
  "startDate": "2018-09-01T00:00:00.000+00:00",
  "endDate": "2018-10-01T00:00:00.000+00:00",
  "openingDays": [
    {
      "weekdays": {
        "day": "THURSDAY"
      },
      "openingDay": {
        "openingHour": [
          {
            "startTime": "09:00",
            "endTime": "12:00"
          },
          {
            "startTime": "13:00",
            "endTime": "17:00"
          }
        ],
        "allDay": false,
        "open": true
      }
    }
  ]
}

Response 204

Library period 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 period -- malformed JSON at 13:4"

Response 404

Library period id or service point with the given ID is not found

Body

Media type: text/plain

Type: any

Example:

"period 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": {
      "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 /calendar/periods/{servicePointId}/calculateopening

This endpoint helps to calculate due date. The response contains three openings: the requested day, next and previous dates openings which are closest to the requested day. Calculation can based on days or hours to calculate overnight loans. In case of existing amount parameter the requested day will be calculated: date + amount * unit otherwise it returns the date itself

GET /calendar/periods/{servicePointId}/calculateopening
URI Parameters
  • servicePointId: required (string)
Query Parameters
  • startDate: required (string)

    loan start date

    Example:

    2018-11-15
  • unit: (one of day, hour)

    Calculate in days or hours. Default: day.

    Example:

    day
  • amount: required (integer)

    number of loan days or hours (based on unit), to calculate due date.

    Example:

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

    Requested language. Optional. [lang=en]

Response 200

Body

Media type: application/json

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

Response 404

Not found

Body

Media type: text/plain

Type: any

Response 500

Internal server error

Body

Media type: text/plain

Type: any