Developer portal & API experience

Developer portal and API experience design

An API programme is only as useful as the path a developer can find through it. When the right endpoint is hard to locate, authentication is explained in three different places and error codes live in a PDF, integration slows down and support tickets pile up. MadeByCat designs and builds the experience layer of developer portals so technical teams can move from discovery to a working integration with less hand-holding.

Short answer

MadeByCat designs and builds developer portals as products: developer-experience research, API information architecture and catalogue, documentation UX, sandbox and onboarding journeys, clear presentation of authentication, code samples and error states, a design system and responsive frontend. Published work includes Garanti BBVA API Market, the Garanti Ödeme Sistemleri Developer Portal and the TAMI Developer Portal. The APIs and backend systems themselves stay with the client.

Who this is for

Product, platform and API teams whose services are technically ready but hard to adopt: payment providers, platform businesses, software vendors and any organisation that opens APIs to partners or external developers. The common signal is the same — integrations take longer than they should, and the same questions keep reaching the support or solution-engineering team.

The page is about the product type and the engineering problem, not a sector. For the wider picture of bank and finance websites — product journeys, disclosures, investor content — see the banking and finance solution.

Banking and finance web experience

What we design and build

Developer portals fail in specific, repeatable places. We scope the work around those places rather than around page templates.

Developer-experience research: integration intents, user maturity levels, support questions and the points where developers abandon or ask for help.
API information architecture and discoverability: a product → use case → API hierarchy, search and filtering, and a catalogue developers can scan.
Technical documentation UX: reference, guides and change notes structured as one journey instead of separate archives.
Sandbox, onboarding and integration journey: how a developer gets credentials, reaches the test environment and understands the step to production.
Authentication flows presented clearly: what is required, in which order, with examples rather than prose alone.
Content design for code samples and error states: copyable samples, error codes with causes and next steps, and test data where the provider publishes it.
Design system, responsive frontend and web engineering so documentation patterns stay consistent as the API surface grows.
Content management for technical writers and post-launch managed services for releases, updates and improvements.

Scope and what sits outside it

We own the portal experience layer: research, structure, interface, frontend, documentation presentation and, where agreed, its ongoing operation. The API design itself, backend services, payment or core-system processing, API gateways and security certification remain with the client and its platform teams. We work with those teams on content accuracy and on how their requirements are explained to developers, without claiming ownership of the systems behind them.

How an engagement usually runs

Work starts with an inventory of the existing APIs, documentation and support questions, plus interviews or sessions with developers who integrate today. From that we define the information architecture and the integration journey, prototype the critical paths — find an API, authenticate, call the sandbox, resolve an error — and test them before building.

Build follows in increments with the client’s platform team reviewing technical accuracy. After launch, the portal can move into a managed-service model with planned releases, documentation updates and improvements driven by real usage and support signals. Delivery gates, RACI and priority levels follow our published playbook.

Published developer portal work

Garanti BBVA API Market: a search-led API market with services grouped into API categories and documentation woven into discovery; our role covered experience strategy, information architecture, UX/UI, documentation experience and design-system application. Garanti Ödeme Sistemleri Developer Portal: an API catalogue and search across payment product areas, with documentation, test cards, error codes and support content; our role included frontend/platform implementation. TAMI Developer Portal: payment APIs, sandbox paths and a clear distinction between test and production endpoints, also including frontend/platform implementation.

In all three cases the underlying payment APIs and backend systems belong to the client; the case pages describe exactly which layer MadeByCat delivered.

Evidence and related case studies

The live developer portal presents the e-commerce API market with API search, service pages and API categories.
Garanti BBVA API Market
The live portal presents an API catalogue and search with product areas including Virtual POS, Switch, Card Storage, Security Platform and GarantiPay.
Garanti Ödeme Sistemleri Developer Portal
The live portal presents Developer Portal and sandbox paths, payment APIs and a distinction between test and production endpoints.
TAMI Developer Portal

Frequently asked questions

Do you build the APIs or the backend behind the portal?: No. We design and build the developer portal experience and its frontend. API design, backend services and core systems stay with your platform team; we work with them on accuracy and presentation.
Can you work with our existing documentation?: Yes. We start by inventorying what exists — reference docs, guides, PDFs, support answers — and restructure it. Rewriting is decided per item, not by default.
Is this only for banks and payment companies?: No. Our published portal work is in payments, but the problem — making APIs discoverable and integrations faster to start — applies to any organisation exposing APIs to partners or developers.
Can technical writers update the portal without developers?: That is usually a goal. The content model and management approach are chosen so documentation teams can publish within agreed review steps.
Do you support the portal after launch?: Yes, when it is in scope. Managed services cover planned releases, updates and improvements; response targets are agreed in the service contract rather than published as fixed numbers.

Planning or rethinking a developer portal?

Tell us which APIs you expose, who integrates with them and where developers get stuck today. We will outline how we would structure the portal experience.