APIs with FastAPI · Chapter 17 of 26

Files and forms

By the end of this chapter you can take form fields and uploaded files in a FastAPI route, say what a multipart request looks like on the wire, limit what an upload may be, read a large upload a piece at a time, go through an uploaded CSV row by row, and send a file back for the client to download. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Security and real-world behaviour
  • 4 tasks
  • FastAPI
  • In the all labs plan

The first 2 chapters of APIs with FastAPI are free. This one comes with the all labs plan.

Why you need this

Every route so far has taken JSON. The real world sends other things. Sunita's riders photograph each parcel at the customer's door, and when a merchant says "it never came", that photo settles it; the rider's app must upload it. Imran's merchants export the day's orders from their shop software as a spreadsheet and ask, fairly, why they should book 80 parcels one by one. And the merchant dashboard's "Download label" button should save a file to print, not show a page of JSON.

A photo is not JSON, a 40 MB CSV should not be one either, and a label is a file. This chapter is about the three: forms and files coming in, and files going out.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    proof.py: proof of delivery

    Riders photograph every parcel at the door. Make an app with one route: POST /parcels/{awb}/proof takes a multipart form with a field rider_id and a file photo. For an AWB in /workspace/data/parcels.json, save the photo in the folder named by the environment variable PROOF_DIR (default proofs, made if missing) as <awb>.jpg for image/jpeg or <awb>.png for image/png, and answer 201 with awb, rider_id, content_type and bytes (the photo's size).

    An unknown AWB answers 404, any other content type 415, a photo over 2 MB (2097152 bytes) 413 with nothing left saved, and a missing rider_id 422. The check sends photos of 300 KB, exactly 2 MB and one byte more, and a PDF.

  2. Task 2

    bulk.py: a day's bookings from a CSV

    Make an app with one route: POST /parcels/bulk takes a CSV as the file field file, with the header to_pincode,weight_grams,cod_amount. Go through the rows in order (row 1 is the first after the header). A good row is booked with the next AWB, DKG20001, DKG20002 and on, carrying on across uploads. A bad row gets its first problem, checked in this order: unknown pincode (not in pincodes.json), not served (active is false), bad weight (not a whole number from 1 to 30000), bad cod amount (not a whole number, 0 or more), no cash on delivery (cod_amount above 0 where cod is false).

    Answer 200 with booked, failed, and rows: one entry per row, in order, either {"row": n, "awb": ...} or {"row": n, "error": ...}. A different header, or a file that is not UTF-8 text, answers 400.

  3. Task 3

    label.py: a label to print

    Make an app with one route: GET /parcels/{awb}/label answers, for an AWB in parcels.json, a plain text file (content type text/plain) that a browser downloads as <awb>.txt. It has five lines: DakiyaGo; AWB and the AWB; To, the pincode, its city, a comma and its state (from pincodes.json); Weight and the grams followed by g; and COD Rs and the amount, or Prepaid when cod_amount is 0. For example: DakiyaGo / AWB DKG10005 / To 400076 Mumbai, Maharashtra / Weight 1200 g / COD Rs 799.

    An unknown AWB answers 404. The check reads the content type, the Content-Disposition header and every line.

  4. Task 4 · interview question

    Interview: manifest.py, a 200 MB upload

    Make an app with one route: POST /manifests takes the file field file and answers 200 with filename (as the client named it), bytes (its size) and sha256 (the hex SHA-256 of every byte). Read the upload a piece at a time, at most 1 MB (1048576 bytes) per read: the check uploads 5 MB and watches every read.

    The interviewer will ask why not await file.read() for a 200 MB upload, and where the file is before your route runs.

What you will learn

  • Form fields with Form(), and how a form travels.
  • Uploads with UploadFile: multipart requests, where the file waits, and what the client can lie about.
  • Limits: 413 for too large, 415 for the wrong kind.
  • Reading in pieces, for a file of any size, and a CSV row by row.
  • Sending a file back: a media type and Content-Disposition.

More in Security and real-world behaviour

Build "Files and forms" yourself

DakiyaGo, a Jaipur courier startup, takes bookings on WhatsApp. Merchants want an API, and you build it. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of APIs with FastAPI are free. This one comes with the all labs plan.