Why our compliance team rewrites my API specs and I have learned to be grateful

The first time Priya from compliance sent back one of my API specifications covered in red comments, I was annoyed. I had spent a full day designing the endpoint, writing the OpenAPI spec, getting it past code review from two engineers, and felt good about the design. Then compliance got their hands on it. Priya had flagged twelve issues. Twelve. On a single endpoint that returned transaction summaries.

Generate a realistic dark editorial illustration for a fintech engineering article: layered ledger rows, payment states, query bottleneck cues, subtle SQL-console influence, deep navy and amber palette, 16:9, no text, no clip art, no fake corporate stock feel.

By this phase the work was no longer “just build it.” It also builds on what I learned earlier in “The night our database ran out of connections and what I learned about pooling.” Every architecture choice had a people cost, an audit cost, and a recovery cost when production disagreed with the plan. That is roughly when the line between FinanceOps systems and projects like flowscape or ftryos got interesting to me: the design only counts if the operators can live with it.

Editorial supporting image for the section "The Ego Bruise" in the article "Why our compliance team rewrites my API specs and I have learned to be grateful". Show open laptop with SQL query plan or ledger-like table visible, printed reconciliation notes, payment terminal receipt, notebook full of arrows and constraints for "Why our compliance team rewrites my API specs and I have learned to be grateful". Focus on one operational artifact that makes the post feel lived-in rather than conceptual. Color palette: deep blues, oxidized steel, warm amber monitor spill. Mood: tense but controlled, operational, carrying team and system weight at the same time. Composition: 16:9 landscape image, documentary/editorial feel, no text overlays, no stock-photo polish. Avoid: No floating database icons, no cartoon locks, no holograms, no generic fintech stock imagery, no text overlays.

The Ego Bruise

My initial reaction was defensive. These were not engineering concerns, they were compliance nitpicks. Why was the response including the customer email address when the consuming application only needed the customer ID? Why was the error response revealing internal service names in the stack trace? Why was the pagination cursor exposing the database row ID?

Every single flag was valid. I just did not want to hear it from someone who had never written a line of production code. That reaction was entirely about my ego and had nothing to do with the quality of her feedback. In fintech, your API surface is a regulatory document whether you designed it that way or not. Every field you expose is a potential data leak. Every error message is a potential information disclosure. Every ID scheme reveals something about your internal architecture.

Priya was not being difficult. She was doing exactly what a compliance officer should do in a regulated financial company. I was the one who was failing to see API design as a cross-functional concern.

What Compliance Catches That Engineers Miss

Engineers optimize APIs for developer experience. Clean interfaces, consistent naming, helpful error messages, complete data in responses so the frontend does not need extra round trips. These are all good instincts in most contexts. In fintech, every one of them can create a regulatory problem.

• Returning full customer objects when the consumer only needs an ID violates data minimization principles
• Descriptive error messages that include field values can leak PII into log aggregators
• Sequential numeric IDs let anyone enumerate your customer base by incrementing the URL
• Timestamps with timezone information can reveal geographic location of financial activity
• Verbose validation errors on authentication endpoints help attackers map your user base

None of these are bugs in the traditional sense. The API works correctly. The data is accurate. The errors are informative. But from a compliance perspective, each one is a finding in an audit. And in fintech, audit findings turn into remediation timelines, which turn into engineering work that displaces feature development.

The Review Process We Built

After the initial bruise healed, I proposed making compliance review a formal step in our API design process. Not for every endpoint, but for any endpoint that handles customer data, financial transactions, or authentication flows. The process is lightweight.

1. Engineer writes the OpenAPI spec and gets technical review from another engineer
2. Spec goes to compliance with a one-page summary of what data flows through the endpoint
3. Compliance reviews for data minimization, information disclosure, and regulatory requirements
4. Engineer and compliance meet for 30 minutes to walk through any flags
5. Engineer implements changes and compliance signs off before the PR merges

The 30-minute meeting is the key step. Most of Priya’s flags have straightforward fixes once you understand the concern. Remove the email from the response. Replace sequential IDs with UUIDs. Strip internal service names from error responses. Reduce timestamp precision. The conversation takes 30 minutes. The fixes take an afternoon. The alternative is an audit finding that takes weeks to remediate after the code has been in production for months.

How It Changed My API Design

After six months of compliance review, I started designing APIs differently from the start. My default shifted from “return everything the frontend might need” to “return the minimum data required for this specific use case.” The resulting APIs are actually better, not just from a compliance perspective but from an engineering one.

• Response payloads are smaller, which improves performance
• Endpoints are more focused, which makes them easier to test and document
• Error responses are generic enough to be safe but structured enough to be useful
• The API surface area is smaller, which means less to maintain and version

Create a realistic systems-style editorial image: simplified financial workflow, tidy relational structure, subtle success signal, graphite and ledger-green palette, 4:3, no text labels, no infographic clip art.

Operator mode means you inherit every downstream consequence. The code path is only half the story; the other half is how the decision warps planning, trust, and execution speed. I kept relearning that lesson while building ftryos and pipeline-sdk.

The best API review I ever got came from someone who does not write code. Compliance taught me that good API design in fintech means designing for the auditor, not just the developer.

I still feel a small twinge when Priya sends back a spec with red marks. But now it is the same feeling I get during a good code review. Someone is making the work better by catching what I missed. The only difference is that compliance catches a category of issues that engineers are not trained to see. We optimize for correctness and usability. They optimize for risk and exposure. Both perspectives belong in the design process, and I wasted months treating one as more legitimate than the other.