Blog
Mert Özen's blog posts on software development, backend, frontend, and DevOps.
API Review and Governance: A Review Checklist, Documenting Design Decisions and Designing the Bookstore Public API End to End
API review should happen on the contract pull request before code is written, with a written checklist and as advice rather than approval; everything tools can check is left to tools, and people look at meaning, consumers and security. At Bookstore we review a partner's draft with lint and people, turn a review finding into a new lint rule, collect the ADRs and the API inventory, design the purchase approval API end to end with real responses, and close the series.
API-First with OpenAPI 3.2: Design-First Flow, Linting with Spectral, Breaking Change Diffs and Mock Servers
In a design-first flow the OpenAPI contract is a build input: every pull request lints the style guide, looks for breaking changes against the target branch, and checks the freshness of the generated client and drift against the document generated from the code. At Bookstore we see with real output why a Spectral rule never failed, why oasdiff counted a removed parameter as only a warning, the drift check that found the old RPC endpoint, the Prism mock, and Angular types from openapi-typescript.
Bulk, Batch and Asynchronous APIs: Bulk Operations, Partial Success, Webhooks or Polling, and the Rate Limit Contract
The contract of a bulk API spells out the size limit, which errors reject the whole request and which reject a single line, how partial success is reported, how the outcome is delivered, and the quota. At Bookstore we design the schools' bulk order as a 201 with a line-by-line report, a 422 with allOrNothing and a long-running operation with Prefer: respond-async, add the webhook to the contract, and see the RateLimit header draft and 429 with real responses.
Concurrency, Idempotency and Long-Running Operations: ETag/If-Match, Idempotency-Key, 202 Accepted and Status Monitors
The contract has three tools against concurrent and repeated writes: a required If-Match on every request that changes an existing resource (428 without it), an Idempotency-Key on POSTs that create, and 202 Accepted with a status monitor for work that takes seconds. At Bookstore we see with real responses a price cut that silently disappears, an order resent with the same key, the 409 and 422 cases, and the succeeded, failed and cancelled flows of an invoice PDF long-running operation.
Change-Resilient APIs: Breaking Change Rules, Versioning Strategies, Deprecation (RFC 9745) and Sunset (RFC 8594)
The way to change an API without breaking it is to ship additive changes without a version, define response enums as open from the start, and ship a real breaking change as a new version announced with the Deprecation and Sunset headers. At Bookstore we see with real responses how a new order status breaks a strict .NET client, a dated api-version while replacing author with authors, the RFC 9745 and RFC 8594 headers, and the usage log of a deprecated version.
Collection Endpoints: The Contract for Pagination, Filtering, Sorting, Field Selection and Search
The contract of a list endpoint is more than its item schema; page size rules, an opaque page token bound to the query, a documented sort with a tie-breaker and the error for an unknown parameter are contract too. At Bookstore we replace a decodable Base64 token with an encrypted keyset token and a silently ignored filter with a 400, and discuss the Link header, sparse fieldsets, the AIP-160 filter language and the RFC 10008 QUERY method with real responses.
Error Contracts: RFC 9457 Problem Details, Error Code Catalogs, Validation Errors and Localization
A good error contract is built on RFC 9457 Problem Details and separates the members that stay fixed for machines (type, extensions, errors keys) from the ones localized for humans (title, detail). At Bookstore we tie error types to a catalog, turn validation keys into JSON paths and rule codes, return Turkish errors through Accept-Language, fix a 500 that changed with the environment and a stack trace leak, and write a single interceptor in Angular.
HTTP Method and Status Code Semantics: Safe, Idempotent, PUT or PATCH, and Choosing 200/201/202/204/409/412/422
Choosing methods and status codes should rest on RFC 9110's definitions of safe and idempotent and on a decision rule the team writes down once: 400 for a malformed request, 422 for a valid request a business rule rejects, 409 for a conflict with the resource's state, 412 for an If-Match mismatch. With real responses from Bookstore we cover 201 and Location with POST, creating with PUT, 415 and Accept-Patch with JSON Merge Patch, and the split between 401, 403, 404 and 405.
Resource Modeling and URL Design: Collections, Sub-resources, Naming, Custom Actions and When You Need a Verb
In good URL design, resources come from the domain's language rather than its tables, every resource has one canonical address, and work that needs a verb becomes either a custom method or a new resource with its own lifecycle. We design Bookstore's institutional order addresses, the singleton cart, the ISBN, UUID v7 and slug id choices, POST /orders/{id}:cancel and a returns resource, with real HTTP responses and Spectral rules.
Why API Design Is an Architectural Decision: Contracts, Consumers, What REST Really Is and Style Guides
API design is an architectural decision because the contract is everything a consumer can observe, and changing it means changing the consumers too. Starting from Bookstore's old RPC endpoint that returns errors inside a 200, we cover Fielding's REST constraints, the Richardson Maturity Model, where HATEOAS really helps, and the Azure, Google AIP and Zalando guidelines, then write our own style guide as an ADR and enforce it with Spectral.
The Bookstore Repo and Reading Map: Where Is the Code and Which Part Is in Which Series?
Bookstore's code lives in a single GitHub repo: main is the reference application, every series is a series/<series-slug> branch and every post a <series-slug>/NN tag. We cover getting a post's code with git switch --detach, seeing the difference between two posts with git diff, experimenting on your own branch, and reading paths for backend, frontend, architecture and team leads.
Bookstore's Technical Structure: Modules, Data Model, Web API and the Angular Client
Bookstore's reference application holds the Catalog, Ordering and Inventory modules in a single ASP.NET Core 10 API, one BookstoreContext with a SQL schema per module, xUnit v3 integration tests and an Angular 22 client. We cover the module map, the data model, the endpoints, the first stock code that deadlocked under concurrent orders and the conditional UPDATE that fixed it, and the steps to run it on Windows.