{"id":25455477,"url":"https://github.com/openactive-archive/booking-api-reference-implementation","last_synced_at":"2026-07-14T19:32:17.443Z","repository":{"id":90319532,"uuid":"143741870","full_name":"openactive-archive/booking-api-reference-implementation","owner":"openactive-archive","description":null,"archived":false,"fork":false,"pushed_at":"2018-09-19T08:55:53.000Z","size":99,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-10-20T05:22:01.561Z","etag":null,"topics":["archived","implementation-support"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openactive-archive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-06T14:41:22.000Z","updated_at":"2024-07-01T16:30:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"8a14fc85-9558-4b86-b7b2-3b526b68162d","html_url":"https://github.com/openactive-archive/booking-api-reference-implementation","commit_stats":null,"previous_names":["openactive-archive/booking-api-reference-implementation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/openactive-archive/booking-api-reference-implementation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openactive-archive%2Fbooking-api-reference-implementation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openactive-archive%2Fbooking-api-reference-implementation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openactive-archive%2Fbooking-api-reference-implementation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openactive-archive%2Fbooking-api-reference-implementation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openactive-archive","download_url":"https://codeload.github.com/openactive-archive/booking-api-reference-implementation/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openactive-archive%2Fbooking-api-reference-implementation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35476729,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-14T02:00:06.603Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["archived","implementation-support"],"created_at":"2025-02-18T00:58:02.344Z","updated_at":"2026-07-14T19:32:17.402Z","avatar_url":"https://github.com/openactive-archive.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Booking API Reference Implementation\n\n## What is this?\n\nIt is a lightweight reference implementation of the Open Active Booking API Specification (v1.0). It is designed to be something that could be run locally as a simple datasource for developing/testing a **broker** application, simulating the **booking system**.\n\n## Aims\n\nIt aims to simulate a set of standard conditions when booking spaces on **opportunities**. It simulates the **leases** created during the booking process, cancellable and uncancellable **offers**, cancellation windows, and the completion of **orders**\nwhere a **broker** notifies the **booking system** that they have taken **payment** from a customer.\n\n## How do I run it?\n\nIt is a self contained Flask application with minimal imports which uses the filesystem as a datastore (this has the advantage of reducing the number of moving parts to install/set up). On startup it creates a minimal set of Events and Offers which can be\nthen used to create Orders. All of these created objects can be seen via the API and also in the filesystem objects contained in a\nlocal_data folder which is created.\n\n## What can I do with it?\n\nYou can use it to aid the development of your Open Active **broker** or Booking API Client library.\n\n## What conditions does it simulate?\n\nIt simulates the following conditions:\n\n- Successful Order Creation\n- Successful Recording of Payment (Order Completion)\n- Successful Order Cancellation\n\nEvent related error conditions:\n- events which are full (0 remainingAttendeeCapacity)\n- events which do not have enough spaces required for the order\n- events which cannot yet be booked\n- events which are in the past\n- events which don't exist\n\nOffer related error conditions:\n- offers which are not yet valid\n- offers which have expired\n- offers which don't exist\n- mismatch of offer and event\n\nOrder related error conditions\n- missing customer details\n- missing broker details\n- missing order item (the event required and number of places)\n- missing accepted offer (the offer chosen by the customer)\n- expiry of the anonymous lease\n\nPayment related error conditions\n- no payment information provided\n- wrong payment amount (payment amount not matching invoice amount)\n- wrong payment currency (payment currency not matching invoice currency)\n\nCancellation related error conditions\n- uncancellable offers\n- offers which could not be cancelled as the cancellation window had expired\n- orders which are in an uncancellable state (i.e. an order which is not in OrderDelivered)\n\nIt simulates:\n- GET requests for Events, Offers, Orders\n- POST requests for creating Orders\n- PATCH requests for updating Orders (notifying payment/cancelling an order)\n\nExamples for these are included further on in this document.\n\n## What does it NOT do in its current implementation?\n\nIt currently does not do the following things:\n\n- simulate or emulate an RDPE feed\n- validation of inputs against the Open Active data model (other tools are available for this)\n- simulation of opportunities other than events (Facility Use/Slots)\n- simulation of events with subEvents and schedules\n- simulation of deletion of created orders which the customer wished to not proceed with (the lease simply expires)\n- restricting further viewing/updating of an order to the broker which created it\n- restricting further viewing/updating of an order to the customer which created it\n\n## What is non-standard in this implementation\n\nThere are two properties on Event which are not part of the Open Active standard, but are present to maintain state around leases and completed orders in the absence of a relational datastore.\n\nThese are:\n\n- 'orderLeases'\n- 'completedOrders'\n\nThey are stripped from the API returns, but are present in the JSON-LD representations of Events stored in the filesystem. These properties must NOT be used in a live implementation.\n\n## Installation/setup instructions\n\nFirst install Python. Python 3.6 or higher is known to work.\n\nClone or download this repository.\n\nChange directory to the downloaded directory.\n\nCreate a virtual environment for the project\n\n`virtualenv -p python3 env`\n\nActivate the virtual environment\n\n`source activate env`\n\nor\n\n`source env/bin/activate`\n\nDepending on how you have installed Python.\n\nYou will then need to install the minimal dependencies in your newly activated environment.\n\n`pip install -r requirements.txt`\n\nNow change directory to the `app` directory.\n\nRun the script to start the Flask app. There are two versions of this. One will create a clean local data environment with a sample set of events and offers.\n\n`source ../scripts/clean_run_flask.sh`\n\nThe other one will use a pre-existing set of data in case you wish to keep using the data environment you've already interacted with but have had to stop Flask for some reason.\n\n`source ../scripts/run_flask.sh`\n\nVisiting the application in a browser will result in a JSON return, instructing you that\n\nhttp://localhost:5000/\n\n## Authentication\n\nAll of the API calls, except for the welcome message are protected. The API can be authenticated against in two ways:\n\n- passing a set of Basic Auth credentials\n  - username : openactive\n  - password : UsingDataToHelpPeopleGetActive\n\n- providing an API key (rr4nlnyhi3tdoonxfysi) in the 'x-api-key' header\n\n## Accept Headers/Content Type\n\nAll data provided to and returned by the API is in a JSON-LD format conforming to the Open Active schema (Modelling Specification version 2.0 / Booking API Version 1.0). This includes all error messages.\n\nData sent to the API should include an 'Accept' header, set to 'application/vnd.openactive.v1.0+json'\n\n## Errors\n\nAll errors are returned to the client with an appropriate HTTP status code and as a JSON-LD formatted response.\n\nErrors are documented in the Booking API Specification v1.0. The text and description in these errors is intended as a guide only.\n\n## What's in the sample data?\n\nThe sample data is generated from the `clean_run_flask.sh` script using the current date as a starting place, with dummy events starting at 8am.\n\n- An event which has already passed\n- Two events in the future\n- Offers for each event, some cancellable, others not\n- A sample historic order\n\n## Examples\n\n### Get Event\n\n\n\n\n### Get Offer\n\n\n### Get Order\n\n\n### Create Order\n\n```json\n{\n\t\"@context\": \"https://openactive.io/ns/oa.jsonld\",\n\t\"type\": \"Order\",\n\t\"broker\": {\n\t\t\"type\": \"Organization\",\n\t\t\"name\": \"MyFitnessApp\",\n\t\t\"url\": \"https://myfitnessapp.example.com\"\n\t},\n\t\"customer\": {\n\t\t\"type\": \"Person\",\n\t\t\"email\": \"geoffcapes@example.com\",\n\t\t\"givenName\": \"Geoff\",\n\t\t\"familyName\": \"Capes\"\n\t},\n\t\"acceptedOffer\": [{\n\t\t\"type\": \"Offer\",\n\t\t\"id\": \"http://localhost:5000/offers/12341\"\n\t}],\n\t\"orderedItem\": [{\n\t\t\"orderQuantity\": \"1\",\n\t\t\"orderedItem\": {\n\t\t\t\"type\": \"Event\",\n\t\t\t\"id\": \"http://localhost:5000/events/1234\"\n\t\t}\n\t}]\n}\n```\n\n### Update Order (payment)\n\n\n### Update Order (cancellation)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenactive-archive%2Fbooking-api-reference-implementation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenactive-archive%2Fbooking-api-reference-implementation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenactive-archive%2Fbooking-api-reference-implementation/lists"}