test-interface

Open Booking API Test Interface

This is the specification and JSON-LD namespace for the test interface of the Open Booking API.

Status: Draft Please Provide Feedback via GitHub

Status

This specification and namespace is in a draft state, however every effort will be made in subsequent revisions to maintain the IDs associated with the enumerations defined here.

Overview

This interface must be implemented by the Booking System to make use of the “Controlled” test mode within the OpenActive Test Suite. For the “Random” test mode, opportunities that match the criteria specified in the TestOpportunityCriteriaEnumeration enumeration must exist in the Booking System.

This interface and associated namespace is defined as a convenience to aid testing of the Open Booking API. Booking Systems MUST NOT expose this interface in production environments.

Namespace

The namespace MUST be referenced using the URL "https://openactive.io/test-interface" (which will return the JSON-LD definition if the Accept header contains application/ld+json), and is designed to be used in conjunction with the "https://openactive.io/" namespace.

Test Interface Endpoints

The Test Interface Endpoints are specified relative to the same Base URI that is defined in the Open Booking API.

Datasets Endpoints

To use the “Controlled” test mode within the OpenActive Test Suite, the /test-interface/datasets endpoints must be implemented. They are not required for “Random” test mode.

A testDatasetIdentifier is set in the configuration of the OpenActive Test Suite instance, and is reused across multiple test runs of the same instance. This allows any existing test data to be cleaned up, while still allowing multiple test suite instances to execute against a shared booking system environment simultaneously.

DELETE /test-interface/datasets/:testDatasetIdentifier

This endpoint deletes all opportunities within a given testDatasetIdentifier.

The endpoint is called just once before each test run, when the OpenActive Test Suite is run in “Controlled” test mode.

It must clean up test data from previous test runs for the given testDatasetIdentifier.

Example Request

This request would delete all opportunities within the test dataset “uat-ci”.

DELETE /test-interface/datasets/uat-ci HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1
Example Response
HTTP/1.1 204 No Content
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1

POST /test-interface/datasets/:testDatasetIdentifier/opportunities

This endpoint creates an opportunity in the Booking System, that matches the specified criteria.

The endpoint is called (potentially multiple times) before each individual test starts executing, when the OpenActive Test Suite is run in “Controlled” test mode.

The endpoint must accept a bookable opportunity type, which includes a specific test:TestOpportunityCriteriaEnumeration to which the newly created opportunity just conform, and the appropriate @type of superEvent or facilityUse to disambiguate the type of opportunity to be created. It must also include an organizer or provider @id to specify the Seller within which the opportunity should be created.

The Booking System must create an opportunity of the type specified in @type (taking into account @type of superEvent or facilityUse) matching the criteria specified by test:TestOpportunityCriteriaEnumeration, within the specified notional “Test Dataset” defined by the testDatasetIdentifier within the path.

Example Request

This request would create a new ScheduledSession, within the test dataset “uat-ci”, that meets the criteria specified in https://openactive.io/test-interface#TestOpportunityBookable, for the organizer with @id https://id.booking-system.example.com/organizer/3.

POST /test-interface/datasets/uat-ci/opportunities HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1

{
  "@context": [
    "https://openactive.io/",
    "https://openactive.io/test-interface"
  ],
  "@type": "ScheduledSession",
  "superEvent": {
    "@type": "SessionSeries",
    "organizer": {
      "@type": "Organization",
      "@id": "https://id.booking-system.example.com/organizer/3"
    }
  },
  "test:testOpportunityCriteria": "https://openactive.io/test-interface#TestOpportunityBookable"
}
Example Response
HTTP/1.1 201 Created
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1

{
  "@context": "https://openactive.io/",
  "@type": "ScheduledSession",
  "@id": "https://id.booking-system.example.com/scheduled-sessions/42"
}

Actions Endpoint

POST /test-interface/actions

The /test-interface/actions endpoint is called to simulate a Booking System instigated action for the specified opportunity.

The endpoint is called when the OpenActive Test Suite is run in both “Controlled” and “Random” test modes, only for those tests that depend on test action functionality being available in the Booking System.

If this endpoint is not implemented, the features whose tests depend on this endpoint must be configured to “disabled-tests” mode, to allow the test suite to run successfully.

The Booking System must respond with a 204 status code and an empty body to indicate success.

Example Request

This request would execute the simulation specified by test:SellerRequestedCancellationSimulateAction on the ScheduledSession with @id of https://id.booking-system.example.com/session-series/42.

POST /test-interface/actions HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1

{
  "@context": [
    "https://openactive.io/",
    "https://openactive.io/test-interface"
  ],
  "@type": "test:SellerRequestedCancellationSimulateAction",
  "object": {
    "@type": "ScheduledSession",
    "@id": "https://id.booking-system.example.com/scheduled-sessions/42"
  }
}
Example Response
HTTP/1.1 204 No Content
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1

Namespace

Properties

(Class) Property Expected Type Description
(schema:Event)
test:testOpportunityCriteria
test:TestOpportunityCriteriaEnumeration The opportunity criteria which the Event conforms to.

Classes

Class subClasses Description
test:OpenBookingSimulateAction schema:Action An action that invokes a simulation of a specific behaviour within the booking system.
test:TestOpportunityCriteriaEnumeration schema:Enumeration An enumeration of test opportunity criteria to which an opportunity must conform.
test:AccessCodeUpdateSimulateAction test:OpenBookingSimulateAction Simulate an accessCode Update.
test:AccessPassUpdateSimulateAction test:OpenBookingSimulateAction Simulate an accessPass Update.
test:ChangeOfLogisticsSimulateAction test:OpenBookingSimulateAction Simulate a Change of Logistics.
test:CustomerNoticeSimulateAction test:OpenBookingSimulateAction Simulate a Customer Notice.
test:OpportunityAttendanceUpdateSimulateAction test:OpenBookingSimulateAction Simulate an Opportunity Attendance Update.
test:ReplacementSimulateAction test:OpenBookingSimulateAction Simulate a Replacement.
test:SellerRequestedCancellationSimulateAction test:OpenBookingSimulateAction Simulate a Seller requested cancellation.
test:SellerRequestedCancellationWithMessageSimulateAction test:SellerRequestedCancellationSimulateAction Simulate a Seller requested cancellation, with a cancellationMessage provided.

Enumeration Values

Type Value Description
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookable Bookable Opportunity with Bookable Offer, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted. If both free and paid opportunities are supported by the Booking System, the resulting opportunity should be randomly either free or paid.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookableAdditionalDetails Bookable Opportunity with Bookable Offer, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted, with openBookingFlowRequirement of https://openactive.io/OpenBookingIntakeForm.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookableCancellable Bookable Opportunity with Bookable Offer, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted, without latestCancellationBeforeStartDate, and with allowCustomerCancellationFullRefund.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookableCancellableOutsideWindow Bookable Opportunity with Bookable Offer, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted, except with latestCancellationBeforeStartDate outside of range; and with allowCustomerCancellationFullRefund as true.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookableCancellableWithinWindow Bookable Opportunity with Bookable Offer, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted, with latestCancellationBeforeStartDate in range and with allowCustomerCancellationFullRefund as true.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookableFree Bookable Opportunity with Bookable Offer, with Offer.price == 0
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookableFreeAttendeeDetails Bookable Opportunity with Bookable Offer, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted, with Offer.price == 0, and openBookingFlowRequirement of https://openactive.io/OpenBookingAttendeeDetails.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookableNoSpaces Bookable Opportunity with Bookable Offer, and includes at least one Offer with prepayment value that is either https://openactive.io/Required or omitted, except with remainingAttendeeCapacity == 0
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookableOutsideValidFromBeforeStartDate Bookable Opportunity with Bookable Offer, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted, except with startDate outside of range of validFromBeforeStartDate.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookablePaid Bookable Opportunity with Bookable Offer, with Offer.price > 0, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookablePaidAttendeeDetails Bookable Opportunity with Bookable Offer, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted, with Offer.price > 0, and openBookingFlowRequirement of https://openactive.io/OpenBookingAttendeeDetails.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookablePaidTaxGross Bookable Opportunity with Bookable Offer, with Offer.price > 0, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted, and taxMode of the seller is https://openactive.io/TaxGross.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookablePaidTaxNet Bookable Opportunity with Bookable Offer, with Offer.price > 0, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted, and taxMode of the seller is https://openactive.io/TaxNet.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookablePrepaymentOptional Bookable Opportunity with Bookable Offer, where at least one Offer has a prepayment value of https://openactive.io/Optional.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookablePrepaymentUnavailable Bookable Opportunity with Bookable Offer, where at least one Offer has a prepayment value of https://openactive.io/Unavailable and a price greater than 0.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookableTwoSpaces Bookable Opportunity with Bookable Offer, and includes at least one Offer with prepayment value that is either https://openactive.io/Required or omitted, except with remainingAttendeeCapacity == 2
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityBookableWithinValidFromBeforeStartDate Bookable Opportunity with Bookable Offer, and includes at least one Offer with a prepayment value that is either https://openactive.io/Required or omitted, with startDate in range of validFromBeforeStartDate.
test:TestOpportunityCriteriaEnumeration https://openactive.io/test-interface#TestOpportunityNotBookableViaAvailableChannel availableChannel of the Offer does not include https://openactive.io/OpenBookingPrepayment