template: architecture-decision-record
# These are optional metadata elements. Feel free to remove any of them.
status: "{proposed | rejected | accepted | deprecated | … | superseded by ADR-0123}"
date: {YYYY-MM-DD when the decision was last updated}
decision-makers: {list everyone involved in the decision}
consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}

{short title, representative of solved problem and found solution}

Context and Problem Statement

{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question. Consider adding links to collaboration boards or issue management systems. Make the scope of the decision explicit, for instance, by calling out or pointing at structural architecture elements (components, connectors, ...).}

{Describe the current state: the existing topology, constraints or legacy workflows in place today, and why that state no longer meets the requirement.}

Decision Drivers

Optional — remove this section if you don't need it.

• {decision driver 1, for instance, a desired software quality, faced concern, constraint or force}
• {decision driver 2}
• {a constraint the decision must respect, e.g., security policy, infrastructure limit, or a vendor or SaaS limitation}
• {an architecture principle the decision should align with, e.g., "API First", "Cloud First", "Least Privilege"}
• …

Considered Options

• {title of option 1}

• {title of option 2}

• {title of option 3}

• …

• {title of option dismissed early} — not taken forward, because {reason it was ruled out before evaluation, e.g., violates a security principle}

Decision Outcome

Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.

Consequences

Optional — remove this section if you don't need it.

• Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
• Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
• Bad, because {it creates architecture debt: what it is, and the trigger for paying it down}
• Neutral, because {it is a tactical solution: its expected lifetime, and what replaces it}
• …

Confirmation

Optional — remove this section if you don't need it.

{Describe how the implementation / compliance of the ADR can/will be confirmed. Is there any automated or manual fitness function? If so, list it and explain how it is applied. Is the chosen design and its implementation in line with the decision? E.g., a design/code review or a test with a library such as ArchUnit can help validate this. Note that although we classify this element as optional, it is included in many ADRs.}

Pros and Cons of the Options

Optional — remove this section if you don't need it.

{title of option 1}

{example | description | pointer to more information | …}

• Good, because {argument a}
• Good, because {argument b}
• Neutral, because {argument c}
• Bad, because {argument d}
• …

{title of other option}

{example | description | pointer to more information | …}

• Good, because {argument a}
• Neutral, because {argument b}
• Bad, because {argument c}
• …

Evaluation Summary

Optional — remove this section if you don't need it.

{Where several options are close, rate them side by side. Keep the criteria that matter for this decision and delete the rest.}

Alignment to Principles

Optional — remove this section if you don't need it.

More Information

Optional — remove this section if you don't need it.

{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when/how this decision the decision should be realized and if/when it should be re-visited. Links to other decisions and resources might appear here as well.}

Governance

Related Decisions and Documents

Review Feedback

template: architecture-decision-record
status: accepted
date: 2026-10-02
decision-makers: Solution architect; Lead back-end engineer
consulted: Security architect; Lead front-end engineer
informed: Product owner; Support team

ADR-AB-0002 Expose booking as a public REST API behind a gateway, identified by a widget key

Context and Problem Statement

The widget runs in a customer's browser, inside an iframe on a website the vendor does not control (ADR-AB-0001). To show free times and to hold, confirm, change and cancel bookings it must call the booking platform. The platform's capability may later be reached by other callers too, such as a business's own tools.

How is the booking capability exposed, so that a browser on any registered website can use it, an anonymous customer can book without an account, a public endpoint resists abuse, and the interface can change without breaking the widgets already installed on other people's sites?

Decision Drivers

• Callable from a browser on a third-party site, with no server work for a small business that has no developer.
• Anonymous customers: booking needs no account, so there is no per-customer login to authenticate with.
• A public endpoint will be abused: it needs origin control, rate limits and a way to shut off one business without affecting the others.
• An installed widget cannot be recalled: the interface must be stable and versioned, with notice before it changes.
• Low cost and complexity for a small team to run.

Considered Options

• A public REST API behind an API gateway, identified by a public widget key restricted to the domains the business registers, with the major version in the path
• A GraphQL endpoint with the same key
• A proxy hosted by each business: its server calls the platform with a secret key, and the widget calls that proxy
• OAuth sign-in for every customer — not taken forward, because customers book anonymously (no account is a requirement)

Decision Outcome

Chosen option: "A public REST API behind an API gateway, identified by a widget key", because it works from any registered site without a server on the business's side, maps directly onto the resources a booking is made of (services, availability, holds, bookings), and puts every cross-cutting control in one place, the gateway.

Each request carries the business's public widget key, which identifies exactly one business. The gateway checks the calling domain against those the business registered, applies a rate limit per business, and routes to the services. Writes carry an idempotency key so a repeated request is safe. The contract, with its errors and limits, is ICR-AB-0001.

Consequences

• Good, because a business installs one snippet and runs nothing.
• Good, because the gateway is the single place for origin checks, rate limits, tracing and shutting off a key.
• Good, because REST's resources, status codes and cacheable reads suit the operations, and the contract is easy to describe and test.
• Bad, because the widget key is public: it identifies a business but proves nothing about the caller. Abuse control therefore rests on registered origins, rate limits and bot protection, none of which is authentication.
• Bad, because a booking takes several calls (search, hold, confirm), where a more specialised interface could take fewer.
• Bad, because a version in the path means supporting an old version for as long as widgets that use it remain installed; the contract promises 90 days' notice before a breaking change.
• Neutral, because a different style such as GraphQL could be added later behind the same gateway without changing this decision.

Confirmation

Pros and Cons of the Options

Public REST API behind a gateway, identified by a widget key

• Good, because it works from any registered site with nothing for the business to host.
• Good, because the gateway centralises the controls a public endpoint needs.
• Bad, because the key is a public identifier, not a secret.

GraphQL endpoint

• Good, because the widget could fetch exactly what a screen needs in one call.
• Bad, because rate limiting by cost, caching and abuse control are harder on a single flexible endpoint, and the widget's few screens do not need the flexibility.
• Bad, because the team has less experience of running it.

A proxy hosted by each business

• Good, because the platform's key stays secret on the business's server.
• Bad, because it requires a developer and a server for every business, which defeats the one-snippet install.
• Bad, because each proxy is a place for a business to get the contract wrong.

Evaluation Summary

More Information

The gateway is built on the library's Integration API Management (External) pattern, which is why the controls above are the ones that pattern lists for crossing a trust boundary.

Governance

Related Decisions and Documents