AI skill: pre-submission API request review

Before your integration goes through Resamania's test ("recette") phase described in Getting started, you can run this skill with your own AI coding agent to self-review it first. It inventories every Resamania API call your codebase makes, checks it against our conventions, and produces a report you can share with our API team — the fastest way to reduce back-and-forth during the review.

This does not replace Resamania's own review before opening production endpoints; it resolves the most common issues before that review starts.

What it checks

1. Endpoint inventory — every endpoint called, its business purpose, and where it's used, as a table.
2. Required parameters — every required field (per the OpenAPI spec) is always supplied.
3. PII / security audit — no personal data leaking into logs, analytics, or third-party requests.
4. Backend-only enforcement — the API is never called directly from a browser or mobile app.
5. client_credentials headers — x-user-club-id and x-user-network-node-id are always both present when that grant type is used.
6. Workflow sequencing — business flows (sale, mandate/signature, registration, booking...) follow the documented call order, with no mandatory step skipped.
7. Additional hygiene checks — grant-type correctness, IRI usage, payment idempotency, pagination, rate-limit handling, credential hygiene, webhook setup.

How to use it

Option A — save it as a reusable skill. If your AI coding agent supports skill files (e.g. Claude Code), save the block below as .claude/skills/resamania-api-review/SKILL.md in your integration's repository, then ask your agent to run it (e.g. /resamania-api-review).

Option B — one-off prompt. Paste the same block directly into your AI coding agent's chat, pointed at your integration's codebase.

---
name: resamania-api-review
description: Pre-submission review of a Resamania API partner integration — endpoint inventory, required-parameter check, PII/security audit, backend-only enforcement, client_credentials header check, and workflow-sequencing check against doc.resamania.com. Use before requesting Resamania's test/recette phase.
---

You are reviewing a partner integration with the Resamania API (doc.resamania.com) before it is
submitted to Resamania's API team for the test ("recette") phase. Work only from what is actually
in this codebase — do not assume a call exists because the documentation describes it.

Source of truth: fetch https://doc.resamania.com/for-agents first, then the specific pages it
points to for the domains this integration touches (sale, auth, contacts, booking, webhooks,
API reference).

Perform the following checks, in order:

1. Endpoint inventory. Find every HTTP call this codebase makes to the Resamania API / API
   Gateway. For each one, produce a row in a markdown table: Method, Path (with placeholders,
   e.g. `/{clientToken}/sales/{id}/payments`), Business purpose (what it does for the end user /
   club, in plain language), Where it's called from (file:function), and the doc page it
   corresponds to. This table is meant to be shared as-is with Resamania's API team.

2. Required parameters. For each endpoint in the inventory, open the matching OpenAPI spec under
   /api-reference/ and list its required request parameters. Confirm the code always supplies
   every one of them — flag any call site where a required field is conditionally omitted,
   defaulted to null, or only set on some code paths.

3. PII / security audit. Flag anywhere the integration might leak personal data: names,
   addresses, phone numbers, emails, IBAN/payment details, or health/fitness data appearing in
   logs, analytics events, error trackers (Sentry, etc.), or third-party requests. Confirm
   responses are trimmed to only the fields the integration actually needs before being
   forwarded, stored, or logged. Confirm anonymised contacts (`isAnonymous: true`) are handled
   correctly and never re-populated with stale personal data.

4. Backend-only enforcement. Confirm the Resamania API / Gateway is only ever called from
   server-side code. Flag any call originating from a browser bundle, mobile app binary, or any
   code path where the request (and therefore its `x-gravitee-api-key` / OAuth credentials) would
   be visible to an end user's device. Every such call must instead go through the partner's own
   backend, which then exposes a filtered response to the client.

5. client_credentials headers. For every token obtained with `grant_type=client_credentials`,
   confirm that literally every subsequent API call using that token sets both `x-user-club-id`
   and `x-user-network-node-id` explicitly — this grant is generic/non-personalized and carries no
   implicit context. Flag any call that omits either header, even if it currently "works" (e.g.
   single-club tenants where the header is normally optional) — for `client_credentials` both must
   always be present.

6. Workflow sequencing. For each business flow implemented (e.g. selling to an existing contact,
   mandate/contract/signature, online registration, cancellation, booking), compare the actual
   call sequence in the code against the documented sequence on the corresponding page (linked
   from https://doc.resamania.com/for-agents). Flag any missing mandatory step (e.g. no debt check
   before a sale, no `GET .../check` before settling payment, no contract display before
   requesting a signature, missing catalog-context filters, no idempotency guard on payment
   calls).

7. Additional hygiene checks.
   - Correct grant type for each use case (no `client_credentials` where a contact- or
     club-scoped grant is actually required, or vice versa).
   - IRIs used consistently (no bare numeric IDs passed where an IRI is expected).
   - Payment calls (`POST .../sales/{id}/payments`) are protected against duplicate submission on
     retry/timeout.
   - Pagination is handled correctly (no hardcoded assumption of a fixed page size, no unbounded
     loops).
   - Rate-limit handling: exponential backoff on `429`, no tight polling loop where a webhook
     subscription would do.
   - No OAuth `client_secret`, access tokens, or refresh tokens hardcoded, committed, or logged in
     plaintext.
   - Sandbox and production credentials are kept in separate configuration, never mixed.
   - If webhooks are used: the endpoint validates the `X-User-Club-Id` /
     `X-User-Network-Node-Id` headers and a distinct URL is configured per environment
     (prod/sandbox/overseas).

Output: a single markdown report containing the endpoint inventory table from check 1, and a
pass/fail list for checks 2-7, each failure with a file/line reference and a one-line fix
suggestion.

After running it

Share the resulting report with Resamania's API team ([email protected]) alongside your test-phase request.

Keeping this current

This skill points at doc.resamania.com rather than embedding business rules directly — if a required header or a documented workflow changes, updating the relevant page keeps every partner running this skill in sync automatically.