Data model and API

35 minBeginner

Data model and API

The screens from the last lesson tell you what data the reorder app needs and what it must be able to do. This lesson turns them into four tables and four endpoints, with the few rules that keep Ravi's orders correct when prices change and his mobile data drops.

By the end you can

Read the tables and endpoints off a screen flow, one screen at a time
Design the tables for shops, products, orders and order lines, with keys, money in cents and a fixed list of statuses
Decide what an order must copy at the moment it is placed, and what it may point at
Write endpoints that take the shop from the sign-in token and answer with clear status codes
Make "repeat this order" safe to retry, so a weak signal never doubles an order

The everyday picture

Picture the wholesale counter at a market before any app existed. Behind the counter is an order book. Each page is one order: the shop's name at the top, the date, then one line per product with the quantity and the price that day. At the bottom, a stamp shows where the order is: taken, packed, sent.

Shop owners never walk into the stock room or write in the book themselves. They hand a slip through the window, the clerk checks it ("we don't sell that tin any more"), writes the page and hands back a receipt with the order number.

Your app needs the same two things. The order book is the data model: the tables and the rules about what goes in them. The window and the clerk are the API: the few requests the app may make, what it must send, and what it gets back. Get the book's columns right and the clerk's checks right, and the app on the phone stays simple.

From screens to tables and endpoints

Start from the screen flow you sketched and tested in Screens and flows, not from a blank database. For each screen, write two things: what it shows and what the person does there. For the reorder app, the notes look like this:

Output

Screen          Shows                                   Does
Last orders     date, status, number of items, total    tap one order
Order detail    each line: name, qty, price then/now    tap "Repeat"
Repeat          the same lines with + and - steppers    tap "Confirm"
Status          order number, status, when it changed   nothing
Weekly summary  items and money spent in one week       pick a week

Now read the notes like a detective. The nouns that keep coming back are candidates for tables: shop, order, line, product. Not every noun becomes a table. "Status" is one value of an order, so it is a column. "Week" is a way of grouping orders by date, so it is a query, not something you store.

The "Shows" column becomes the read requests. Each screen should get everything it needs from one request. On a weak mobile signal a single request can take a second or more, so a screen that makes one call per order feels broken. The "Does" column becomes the write requests. Here there is only one real write: "Confirm" creates a new order. Tapping an order or picking a week only reads.

An endpoint is one of those requests: a method and a path, such as GET /v1/orders. Reads use GET, which never changes anything. Creating something uses POST. The /v1 at the front leaves room for a second version later without breaking phones that still run the old app. APIs done right covers methods and paths in more depth.

Quick check

The Status screen shows the order number, its status, when the status last changed and the list of products. Which request should it make?