API Proof of Concept: How Analysts Build POCs and Demos That Settle Decisions

An API proof of concept answers one feasibility question with evidence, fast. It is not the start of the build: it is a two-day experiment that settles a decision, whether an API really supports the process the business case depends on. And an analyst with a Bruno or Postman collection can build most of one without writing application code.

To build an API proof of concept: write the decision it must settle as a yes or no question with measurable success criteria; timebox it to about two days; get credentials and a first successful call; chain the happy path; run the failure cases and prove webhook delivery; then record each criterion’s result with evidence and rehearse a short demo. If the API does not exist yet, mock it from its OpenAPI file and run the same collection against the mock.

APIs for Analysts, part 7 of 8. Previous: Part 6, chaining API requests with JavaScript. Next: Part 8, the analyst who can send a request. All parts: series overview.

I have seen more integration arguments ended by a twenty-minute demo than by any number of architecture meetings. A steering committee cannot evaluate “we believe the vendor API supports this”; it can evaluate a green run report and a live decline handled correctly. This article is how to produce that, using the Stripe sandbox flow from Part 6 as the running example. The broader technical skill set behind it is mapped in The Technical Skills Guide for BAs.

What is an API proof of concept, and what should it prove?

A proof of concept tests feasibility: can this work? It is easy to confuse with two neighbors, and merging them is how a two-day POC becomes a two-month project.

	Proof of concept	Prototype	Pilot
Question	Can it work technically?	Do users understand and want it?	Does it work for real?
Audience	Decision makers, architects	Users, product	Operations, business owners
Built with	API requests, mocks, scripts	Screens, clickable mockups	The production solution
Lifespan	Days, then discarded	Weeks, then discarded	Weeks to months, then scaled
Output	A decision with evidence	Design feedback	Go-live readiness

An API POC is almost always triggered by an uncertain gap from an API analysis: the documentation suggests the API can do something, nobody has proven it, and a decision is waiting. The POC turns “suggests” into “proven” or “disproven”.

Write the question as a hypothesis with criteria before touching any tool:

We believe Stripe’s API can support partial refunds initiated by our operations console, with a free-text operations reason, reconcilable daily against our ledger.

We will know this is true when:

1. A partial refund of a captured payment succeeds via the API.
2. An operations reason of up to 500 characters is stored and returned with the refund.
3. A refund event is delivered to a webhook endpoint with the refund ID and payment reference.
4. A list call returns the refunds for a given day with enough data to match them to ledger entries.
5. A refund exceeding the remaining amount is rejected with a machine-readable error.

Five criteria, each answerable with a request. If a criterion cannot be proven with a request, a response, or a captured event, it does not belong in an API POC.

How do you scope a POC so it finishes in two days?

With a one-page charter that says what is out as clearly as what is in.

# POC charter: <name>

Decision it settles:   <the go / no-go / choose-between question>
Decision owner:        <who decides, and when>
Hypothesis:            We believe ... We will know when ...
Success criteria:      1..5, each provable by a request or event
Out of scope:          UI, performance, production credentials, error
                       messaging copy, anything not in the criteria
Timebox:               2 days; stop and report at the end regardless
Environment:           <sandbox URL or mock>, test credentials only
Kill criteria:         Stop early if <credentials unavailable after day 1 / criterion 1 fails>
Evidence produced:     Collection, run report, captured events, findings table

The kill criteria line is the one people skip and later regret. If criterion 1 fails on the morning of day 1, the answer is already “no” and the remaining time is waste. And if test credentials take a week to provision, the POC is blocked, which is itself a finding worth reporting: on bank programmes, access lead time is regularly the longest task in an integration.

What does a two-day API POC look like?

Block	Goal	Done when
Day 1, morning	Access and first call	Auth works; one read and one write succeed in the sandbox
Day 1, afternoon	Happy path chain	The core flow runs end to end in one collection run with fresh data
Day 2, morning	Failures and events	Each failure criterion is proven; a webhook event is captured
Day 2, afternoon	Evidence and demo	Findings table written; demo rehearsed twice; report exported

For the refund hypothesis, day 1 is the Part 6 chain almost unchanged: create customer, create and confirm payment, partial refund. Criterion 2 is one extra form field, metadata[ops_reason], and one assertion that the retrieved refund returns it unchanged. Criterion 5 is the same refund request with amount larger than what remains, asserting an error comes back instead of a refund.

Build it as a collection from the first minute, not as ad hoc requests to tidy later. The collection is the evidence, the demo script, and the handover to the build team. Nothing gets rebuilt.

How do you POC against an API that does not exist yet?

Mock it from its specification. If the provider or the internal team has an OpenAPI file, even a draft, you can run a realistic fake of the API locally in one command:

npx @stoplight/prism-cli mock openapi.yaml

Prism starts a server, by default on http://127.0.0.1:4010, that validates your requests against the spec and returns the documented examples. Two capabilities make it genuinely useful for POCs and demos:

• Ask for a specific documented response with a Prefer header, for example Prefer: code=422 to get the documented business rule error, so the failure path is demonstrable before anyone has built it.
• Get generated data instead of fixed examples by starting the mock with the dynamic flag, npx @stoplight/prism-cli mock -d openapi.yaml, so repeated calls do not return identical IDs.

Then add an environment to the same collection:

name: mock
variables:
  - name: baseUrl
    value: http://127.0.0.1:4010

The collection now runs against the mock or the real sandbox by switching one dropdown. That switch is where a subtle win hides: when the real API arrives, rerun the same collection against it, and every difference between the mock and the real API is a finding, either the implementation drifted from the contract or the contract was wrong. Postman offers hosted mock servers for the same purpose if your team prefers them. Writing the OpenAPI examples that make a mock convincing is covered in Part 4.

How do you prove webhooks in a POC?

Webhooks are usually half the feasibility question, because the business outcome often arrives asynchronously, and they are the half most POCs skip. Two practical ways to prove them without building a server:

Capture raw deliveries with a request inspector. Services such as webhook.site give you a unique public URL and display every request sent to it, headers and body. Register that URL as the webhook endpoint in the sandbox, trigger the event, and you have the real payload for your evidence pack and your data mapping.

Forward events locally with the provider’s CLI. Stripe’s CLI does this directly:

stripe login
stripe listen --forward-to localhost:4242/webhook
# in a second terminal
stripe trigger payment_intent.succeeded

stripe listen prints a webhook signing secret starting with whsec_ and streams each event to your terminal, even if nothing is listening on the local port, which is enough to capture payloads. stripe trigger fires a real sandbox event on demand.

For evidence, capture three things per event: the event type, the full payload, and the fields you will need downstream, such as the object ID and your metadata reference. Note in the findings that Stripe documents different retry behavior for sandbox and live mode, so a POC cannot prove live retry handling; it can only prove the payload and the signature header exist. Knowing what a POC cannot prove, and saying so, is what makes the rest of the evidence credible. The full set of webhook requirements and test cases is in webhooks explained for analysts.

How do you build a demo that works in front of stakeholders?

Treat it as a scripted performance of the collection. Every request is a story beat, named as a business sentence, and you narrate outcomes, not JSON.

Beat	Request	What you say	What they see
1	Create customer	”A buyer signs up on the marketplace.”	cus_ ID, email
2	Create and confirm payment	”They pay 20 euros by card, and it succeeds.”	status: succeeded, amount: 2000
3	Partial refund with ops reason	”Ops refunds 5 euros for a damaged item, with a note.”	amount: 500, metadata.ops_reason
4	Refund over remaining amount	”What if someone tries to refund too much?”	A clear error, no refund created
5	Webhook terminal	”Our systems are told automatically.”	The refund event arriving
6	Run report	”And all of this reruns in one command.”	Green HTML report

Beat 4 is the one that wins the room. Stakeholders rarely doubt the happy path; they worry about what happens when things go wrong. Showing a failure handled cleanly, live, answers the unspoken question. The same instinct drives good negative test design.

The rules that keep a live API demo from failing in front of the people you most want to impress:

• Fresh data every run. The runId pattern from Part 6 means rerunning never collides with the last rehearsal.
• A pre-flight request. A first request that checks auth and connectivity, run ten minutes before the meeting.
• Collapse the noise. Before the meeting, decide the one or two fields per beat you will point at, and zoom the response pane.
• Hide every secret. Never show a screen with an environment containing a key. Stripe secret keys in particular must never appear in a browser, a slide, or a recording.
• A recorded fallback. Export the run report beforehand, so a network failure costs you thirty seconds, not the meeting:

bru run 20-demo --env sandbox --reporter-html reports/demo-dry-run.html

• Rehearse twice, out loud. The first rehearsal finds the broken request; the second finds the confusing sentence.

Resist building a UI for the demo. A web page calling the API adds CORS problems, secret handling problems, and a day of work, and it shifts the discussion to button colors. The API client is the demo.

What goes in the POC evidence pack?

A findings table that maps each success criterion to a result and its proof, followed by the decision.

#	Criterion	Result	Evidence	Implication
1	Partial refund via API	Pass	Request “Partial refund”, run report	None
2	Ops reason up to 500 chars stored	Pass, with limit	Metadata value accepted at 500, rejected above	Console needs a 500 character limit and counter
3	Refund event to webhook	Pass	Captured charge.refunded payload	Map payment reference from metadata
4	Daily list for reconciliation	Pass	List call with date filter, 100 per page	Paginate; volume check needed before build
5	Over-refund rejected	Pass	Error response captured	Map error to console message
Not provable	Live webhook retry behavior	Not tested	Sandbox retries differ from live	Verify in pilot

Then three short sections: Recommendation (proceed, proceed with conditions, or stop), Conditions and gaps (each becomes a backlog item with an owner), and Handover (the collection location, the environments, and the .env.sample). Record the decision with its date and owner in the programme’s decision log, because six months later someone will ask why this API was chosen.

The collection is the most underrated output. The build team starts from a working, documented set of requests with assertions; testers start from its failure cases, which feed straight into API test case design; and support gets a replayable reference of how the integration is meant to behave.

What mistakes turn a POC into a problem?

• No written question. Without a hypothesis, the POC never ends because it can never pass.
• Gold-plating. Adding a UI, performance tests, or production hardening. That is the build, unfunded.
• Happy path only. It proves the part nobody doubted.
• Hardcoded secrets in the collection. The POC collection gets shared more widely than any other artifact you make.
• Sandbox treated as live. List every known difference in the evidence; overclaiming destroys trust in the rest.
• POC code promoted to production. Scripts built to prove a point are not built to run a business. The collection is a starting point; the integration is designed properly.
• No recorded decision. A demo that ends with “great, thanks” and no decision was a presentation, not a POC.

The APIs for Analysts series

1. What is an API and how it works
2. Your first API collection in Bruno and Postman: requests, environments, variables, and secrets
3. How to analyze an API: capability, data, behavior, limits, and change
4. How to document an API: the sections consumers need, OpenAPI, and the error catalogue
5. How to write API test cases: deriving a complete suite from one endpoint
6. Chaining API requests with JavaScript: variables, scripts, polling, and a full Stripe flow
7. API proof of concept and demos (you are here)
8. The analyst who can send a request: why it is an edge, and a 30-day plan

Beyond the core series, the APIs for Analysts learning path organizes companion articles by level: the API glossary and troubleshooting failed requests for beginners, webhooks and GraphQL at intermediate level, and API design review, versioning and breaking changes, API security testing, and API tests in CI for advanced analysts.

The takeaway

An API proof of concept exists to settle one decision with evidence. Write the question as a hypothesis with criteria that requests can prove, timebox it to two days with kill criteria, and build it as a collection from the first minute. Mock the API from OpenAPI with Prism when it does not exist yet, capture real webhook payloads with a request inspector or the provider’s CLI, and demo it as a business storyboard with a failure case run live. Finish with a findings table, a recorded decision, and the collection handed to the build team.

For the full technical path behind this, start with The Technical Skills Guide for BAs, or take the whole library in The Complete Tech BA Bundle. Got a POC question on your programme right now? Bring it to a 1:1 Tech BA Coaching Call and leave with a charter and a two-day plan.

Ahmed is a Senior Technical Business Analyst with 10+ years in banking and payments. He builds practical guides and tools for analysts at The Tech BA Toolkit.

Tags: Proof of Concept, API, Demos, Stripe, Business Analysis