4. Add endpoints
Your endpoints go in src/routes/index.ts. Open it. It has one endpoint so far:
api.get("/hello", auth.requireAuth, (_req, res) => {
res.json({ hello: auth.context(res)!.user.email, database: db ? "connected" : "in-memory" });
});Three parts to notice:
auth.requireAuthis a guard. It runs before your function and answers401if nobody's signed in. Your function only runs for signed-in users.auth.context(res)tells you who's calling:.userId,.user.email,.rolesand.permissions. It's always worked out on the server from the session, so the caller can't fake it.app.use("/api", api)at the bottom puts all of these under/api, so this one is/api/hello.
A public endpoint
Some endpoints don't need anyone to be signed in, like a status page. Leave the guard out. Add this above the /hello endpoint:
// Anyone can call this one.
api.get("/about", (_req, res) => {
res.json({ app: "notes", version: 1 });
});Save. The server restarts by itself. Try it without signing in:
curl localhost:3000/api/about{"app":"notes","version":1}An endpoint that reads what you send
Now one that takes a message in the request body and sends it back with your email. First import HttpError at the top of the file:
import { HttpError } from "../http/errors.ts";Then add the endpoint below /hello:
// Only signed-in users, with what they sent.
api.post("/echo", auth.requireAuth, (req, res) => {
const message = req.body?.message;
if (typeof message !== "string" || message.length > 200) {
throw new HttpError(400, "VALIDATION_FAILED", "message must be text, at most 200 characters.");
}
res.json({ from: auth.context(res)!.user.email, message });
});Never trust the body. Anyone can send anything, so check the type and the size before you use it. Throwing an HttpError gives the caller the same error format SelfAuth uses everywhere, and the user never sees a stack trace.
Sign in again (the commands are in chapter 2), then:
curl "${H[@]}" localhost:3000/api/echo -d '{"message":"hi there"}'{"from":"maya@example.com","message":"hi there"}Check it worked
Send something that isn't text:
curl "${H[@]}" localhost:3000/api/echo -d '{"message":42}'{"error":{"code":"VALIDATION_FAILED","message":"message must be text, at most 200 characters.","requestId":"50092ce7-4f51-4bb8-a9f0-ecafc20ff2c1"}}And call it without a session. Here that means without -b jar:
curl -s -H 'Content-Type: application/json' -H 'X-SelfAuth-CSRF: 1' localhost:3000/api/echo -d '{"message":"hi"}'{"error":{"code":"UNAUTHENTICATED","message":"Authentication required.","requestId":"8d9b96d4-3798-41ed-9e04-b1e014c19a6c"}}Things to keep in mind
- Every endpoint that changes something needs the CSRF header. That's already true for
/api/echo. APOSTwithoutX-SelfAuth-CSRF: 1is refused before your code runs. The generated React and Vue clients send it for you. - Put routes under
/api. With a frontend, the development server forwards/apiand/authto Express, so these paths work from the browser without extra setup. - When the file grows, move groups of routes into their own files. You'll do that for the notes in chapter 7.
If something went wrong
NOT_FOUND. The path is wrong, or the file didn't save. Check the server's terminal for a restart message.CSRF_FAILED. The request is aPOSTand the header is missing. Did you use"${H[@]}"?HttpError is not defined. Add the import at the top of the file.
Next: Add permissions