Building HTTP Web APIs That Other Apps Call
View All Tags
?status=Placed worked, and ?status=placed gave a 400 Bad Request with no explanation. The reason was only in the log: Failed to bind parameter "Nullable<OrderStatus> status" from "placed". JSON bodies accept any case here, and query strings don't.
A request that listed the same product twice in one order got a 500, and the log had MySQL's Duplicate entry '2-9' for key 'order_lines.IX_order_lines_OrderId_ProductId'. The database was right to refuse. But a mistake in the request should be a 400, and it shouldn't take stock and open a transaction to find out.
The response said "type": 0. The database row said Receipt, because I'd configured EF Core to store enums as strings. Nobody reading the API would know that 0 means a receipt, and adding a value in the middle of the enum would quietly change what every number means.
My IExceptionHandler turned database errors into a 503, and the client got exactly what it should. Then I looked at the log for the error it had handled, and the middleware's line wasn't there. That's a change in .NET 10, and one option brings the line back.
Part 2 created the tables, and they're still empty. In this part the API starts using them: you'll insert, read, change and delete rows through real endpoints, and read the SQL that EF Core sends to MySQL for every one of them. You'll also turn MySQL's refusals, such as a duplicate name, into clear HTTP answers, and stop two people from silently overwriting each other's changes.
ASP.NET Core can generate an OpenAPI document from your endpoints, and what it can work out by itself is a list of paths. It can't know that an endpoint "deletes a category that has no products", or that it can answer 409. Four small methods add what's missing. This guide uses them, and shows the JSON that comes out.
Taking an EF Core entity as a request body, and returning one as a response, is less code. It also ties your API to your database, and hands clients control of columns you never meant to share. Here are three real failures of that approach, on a real API, and the small records that prevent them.
On your machine you want to see every SQL statement. In Production you don't: it's noise, and it costs money to store. ASP.NET Core reads appsettings.json, then the file for the current environment on top of it, so one setting in each gives you both. This guide does that for EF Core's SQL log, and checks it in both environments.
{id:int} in a route means "this route only matches if the value is an integer". The difference from a plain {id} shows when someone sends /categories/abc: one answers 404, the other 400. This guide tries every common constraint with real requests, and covers where Microsoft says to stop using them.
A list endpoint collects options: a search term, a category, a sort, a page. Six parameters on one method is hard to read, and passing them along is worse. [AsParameters] puts them in one record, filled from the query string as if each property were its own parameter. This guide uses it on a real product list, with the one detail ASP.NET Core 10 needs.
