Developers

Testing

A reference app to read, how to see what BookingNinja is doing to your app, a checklist to run before you submit, and the mistakes that come up most.

The example app

BookingNinja's own test suite includes a working app: a fake BoardSheep, which stands in for a board game library for cafés where guests reserve a game for their table's time slot. BookingNinja uses it to test itself end to end. It is not published as a separate download, so these guides reproduce what you need, and the code in them follows its structure.

What it does, so you know what a full app looks like:

  • It is plain PHP with no dependencies. It implements every endpoint in the contract: catalogue, guest-step, availability, collection, holds, holds/confirm, holds/release, settings/options, settings/validate, blocks, actions and events.
  • It checks every signature, and does the whole connect flow with a state, the code exchange, and refreshing tokens before they expire.
  • It keeps a library of titles with several copies of each, and decides which copy a booking gets. A title is unavailable for a slot only when every copy is taken. It leaves a gap between two uses of one copy.
  • It treats holds properly: one live hold for each booking, replaces, the Idempotency-Key, a 409 when a title has gone, and a hold that lapses at expires_at.
  • It sends alerts to staff, with a key so a double click is one alert.
  • It has failure switches that make it answer 503, answer slowly or answer with a body that is not JSON, so you can watch what BookingNinja does.
  • A showcase mode draws every guest block, every staff block type and every field type, which is a quick way to see what each looks like.

See what BookingNinja sends

On Build your own app, choose Recent calls on your app. It lists the last 50 calls BookingNinja made to your app, newest first, kept for 14 days: the venue, the endpoint, whether it succeeded, the status, how long your app took and a short error. The error is always one of these categories. It never holds text from your app or from the network.

Error What it means What to check
timeout Your app did not answer in time The time limits in The guest step
connection_failed BookingNinja could not connect Is your server up, and is the tunnel running?
tls_failed The HTTPS handshake or certificate failed An expired certificate, a wrong name, or a missing intermediate certificate
blocked_address BookingNinja refused the address See below
http_404 and the like Your app answered with that status. The number is the status. A 5xx counts as a failure. A 4xx does not.
invalid_response A 2xx reply whose body is empty, or is not a JSON object Reply with {} rather than nothing
response_too_large The reply was over 2 MB Send less, or send a page at a time
paused BookingNinja did not call, because your app has failed too often See pausing, below
not_usable The installation is not active, the app is suspended or the venue has closed The status on the Apps page
internal_error A fault on BookingNinja's side Try again, then get in touch

blocked_address is one category on purpose, so the log cannot be used to probe BookingNinja's network. It covers a name that does not resolve, a private or reserved address, a port other than 443, an address that is not HTTPS and an address with odd characters in it.

Recent events, on the same page, lists the last 50 events BookingNinja sent, from the last seven days.

A call that looks fine, and was not

A reply can be a good JSON object with a 200 status, and still be refused, because it breaks the contract: a field the schema does not allow, a text that is too long, a unit_price with a decimal point. The call log shows it as a success. What the guest sees is your step missing, and what staff see on the booking is a note that your app "could not be reached, so its step was left out".

So check your replies yourself. The contract files are JSON Schema (2020-12) and are served at https://bookingninja.io/developers/contract/v1/, so any validator can fetch them. Validate your reply against the shape the reference names for the endpoint, for example guest.schema.json#/$defs/guestStepResponse. The examples in these guides are checked against the schemas in the same way.

Break it on purpose

A guest must never be stuck because of your app, so test that too.

  1. Stop your server and make a booking. The guest should book without your step.
  2. Start your server. After 5 failed calls in a row BookingNinja pauses your installation, and then makes one call every 60 seconds to see whether your app is back. Check that your step returns without you doing anything.
  3. Make your server slow for the guest step, past its limit. The step should be skipped.
  4. Cancel a booking that has a reservation. Your app should receive holds/release with the reason cancelled.
  5. Change the time of a booking at the hold stage. Your app should receive a new holds with replaces set.

Before you submit

Go through this list.

Connecting

  • The manifest saves with no errors, and every address in it is HTTPS.
  • Your app checks state and refuses a callback without one, if you have an install_url.
  • It exchanges the code, stores both tokens, and sends the browser to return_url unchanged.
  • It refreshes tokens, one process at a time, and stores the new pair before it uses it.

Every call

  • It rejects a wrong signature, a missing signature and a timestamp more than 300 seconds old. It compares in constant time and uses the raw body.
  • Every reply is a JSON object, even an empty one, in good time and under 2 MB.
  • It replies 404 with an error body to an endpoint it does not implement. Except availability, which every step needs.
  • A repeat with the same Idempotency-Key returns the first response.

The guest step

  • availability answers, even with an empty list.
  • holds answers 409 with the code unavailable and the ids when an item has gone. It keeps one hold for each booking and honours replaces. The expires_at it returns is not earlier than the one it was asked for.
  • holds/confirm is safe to repeat. holds/release answers 200 with {} for a hold or reservation it does not know.
  • Prices are whole numbers in the venue currency's minor units.
  • Pictures, links and every other address in a reply are HTTPS.
  • Every reply validates against the contract.

Staff

  • Buttons only appear if the manifest declares staff_actions.
  • Your drawer has no more than 10 blocks if an action can return it.
  • Alerts use a key.

Before sending it

  • Your listing is complete if you want one: tagline, description, developer name, privacy link, support link or email and an icon.
  • Your secrets are in your server's settings, not in your code.
  • Recent calls has been clean for a while, with no errors you cannot explain.

Common mistakes

What happens Why
The step never appears Your app does not implement availability. A 404 from it skips the step. Or the venue has not switched the step on for the session.
The step never appears, and Recent calls shows success The reply breaks the contract. Validate it.
Your app is never called after a venue connects The installation is still pending: your callback did not exchange the code.
Every call is refused with 401 The signing secret is wrong or was rotated, the body was changed before checking, or your server's clock is more than 300 seconds out.
http_301 or http_302 BookingNinja does not follow redirects. Give the final address as base_url, with no redirect from http:// or to a trailing slash.
blocked_address A localhost address, a private address, a port other than 443, or http://. Use a public HTTPS address on port 443.
A hold is refused, and the step is skipped The expires_at in your reply is earlier than the one BookingNinja asked for, by more than two minutes.
A block or a field is missing from the step Its id was used twice (BookingNinja keeps the first), its type is one BookingNinja does not know, or it had nothing to show.
A picture does not show It is not HTTPS, it is an SVG, it is over 2 MB, or BookingNinja has not copied it yet. It appears on a later view.
A call comes back 403 with insufficient_scope The venue connected before you added the scope. It has to connect again.
Every venue has to connect again You changed base_url, redirect_uri or another address to a new origin, and BookingNinja approved it.
Your tokens stop working all at once A refresh token was used again more than 30 seconds after it was first used. BookingNinja treats that as theft and revokes them all.
The guest paid more than your app quoted The venue adds tax on top of its prices. Tax is added to your lines.
A guest swap is refused The new choice costs more than the booking has paid for. A change after booking cannot raise the price.
Staff are not told about an alert The venue has no active trigger for "An app raised an alert". The reply to your call said delivered was false.

What BookingNinja says when a manifest is wrong

Message What to do
"This is not valid JSON" Look for a missing comma, quote or bracket
"The manifest must be a JSON object, starting with {" The manifest cannot be a list
"The manifest is too long. Keep it under 64 KB." Cut it down
scopes: "x" is not a scope BookingNinja offers. Use one of the scopes in Signatures and tokens
settings.venue[2].key "x" is used more than once. A key can be used once for each level. The same goes for catalogue.attributes.
visible_when.key "x" does not name another field A field's visible_when must name another field in the same list
base_url: must be at most 500 characters long. Shorten the address. The same limit applies to the other addresses.
base_url: must start with https:// before the app can be reviewed Use an HTTPS address