Lab

Lab: Build A REST API For Habitat Zones

Objective

Design and build a Hono REST API that reads and writes zones in your existing Habitat SQLite database.

In this lab, your main job is to specify the HTTP interface. Codex can write the implementation code, but you are responsible for deciding what requests should exist, what data they should accept, what responses they should return, and how you will prove they work.

Success Criteria

Create a dedicated lab folder for the Habitat REST API project.
Clone your existing Habitat SQLite GitHub repository into the new lab folder.
Create a new habitat-rest-api branch for this lab.
Inspect your current habitat.db and identify the table that stores zones.
Ask ChatGPT for help designing RESTful HTTP requests for zones.
Write an api-spec.md file that defines your zone API contract.
Use Codex to implement the API with Hono, Bun, TypeScript, and SQLite.
Test each API route with the LMS HTTP tool or curl.
Save successful request and response examples in api-test-results.md.
Verify that API requests changed the SQLite database.
Explain what you specified as the API designer and what Codex implemented.
Submit a public GitHub branch URL for your completed lab.

Instructions

Open Codex.
Clone your previous Habitat SQLite project.

Use the GitHub repository from your previous Habitat SQLite lab. If you are not sure where to find the repository URL, open your previous lab repository on GitHub, click Code, and copy the HTTPS URL.

In a terminal, run:

git clone <your-previous-habitat-sqlite-repo-url> habitat-rest-api
cd habitat-rest-api
git switch -c habitat-rest-api

Replace <your-previous-habitat-sqlite-repo-url> with your actual GitHub repository URL.

After these commands, your lab should live at:

~/labs/habitat-rest-api

Open the cloned project folder in Codex.

When Codex asks you to choose a folder, select:

~/labs/habitat-rest-api

Make sure Codex is working inside the cloned repository, not inside a brand-new empty folder.

Confirm you are on the lab branch.

Run:

git branch --show-current

You should see:

habitat-rest-api

If you do not see habitat-rest-api, ask Codex to help you create and switch to that branch before you continue.

Optional advanced Git path: if your instructor tells you to use a worktree, and your previous Habitat SQLite project is already cloned at ~/labs/habitat-sqlite-codex, you may create the new lab folder with:

cd ~/labs/habitat-sqlite-codex
git worktree add ../habitat-rest-api -b habitat-rest-api
cd ../habitat-rest-api

Use either the clone path or the worktree path. Do not do both.

Confirm your cloned project has the Habitat SQLite files.

Your project from the previous Habitat SQLite lab should include your SQLite database and the code Codex built or migrated for your Habitat project.

Your project should include files similar to:

habitat.db
schema.sql
package.json
src/

Your exact files may differ. The important pieces are:

a working Habitat SQLite database
the source code for your Habitat project
enough package files for Codex to run or update the project

Inspect your database schema.

Run:

sqlite3 habitat.db ".schema"

Find the table that stores zones. It might be named zones, Zone, or something similar.

If you are not sure which table stores zones, ask ChatGPT to help you interpret the schema.

Ask ChatGPT to help you design the zone API.

Use this prompt:

I am building a REST API for a lunar habitat database.

The first resource is zones. A zone is an area of the habitat, such as Life Support, Greenhouse, Airlock, or Crew Quarters.

I want to design a clean RESTful API before Codex writes the implementation.

Please suggest good HTTP routes for creating, reading, updating, and deleting zones.

For each route, include:
- HTTP method
- path
- request body if needed
- success response shape
- likely error cases
- what database action should happen

Keep the API small and beginner-friendly.

Choose your final API contract.

Create a file named api-spec.md.

Your API must include at least these routes:

GET /zones
GET /zones/:id
POST /zones
PATCH /zones/:id
DELETE /zones/:id

In api-spec.md, document each route with:

method and path
purpose
request body
success response example
error response example
database behavior

For example:

## POST /zones

Purpose: Create a new habitat zone.

Request body:

```json
{
  "name": "Greenhouse",
  "description": "Food production and plant monitoring"
}
```

Success response:

```json
{
  "zone": {
    "id": 3,
    "name": "Greenhouse",
    "description": "Food production and plant monitoring"
  }
}
```

Error response:

```json
{
  "error": "Zone name is required"
}
```

Database behavior: Insert one row into the zones table.

You may adjust the field names to match your actual database schema.

Ask Codex to implement your API.

Use this prompt in Codex:

I have an existing Habitat SQLite project in this folder.

Please inspect the project, especially habitat.db, schema.sql, package.json, and any source files.

I am working on the habitat-rest-api Git branch. Please keep your changes on this branch.

I want you to add a REST API using Hono, Bun, TypeScript, and SQLite.

Important: follow the API contract in api-spec.md. Do not invent different routes unless something in the spec is impossible.

Requirements:

1. Use Hono for the HTTP server.
2. Use Bun to run the server.
3. Use the existing habitat.db SQLite database.
4. Implement these routes:
   - GET /zones
   - GET /zones/:id
   - POST /zones
   - PATCH /zones/:id
   - DELETE /zones/:id
5. Read and write the actual zones table in habitat.db.
6. Return JSON responses.
7. Return helpful error messages for missing zones and invalid request bodies.
8. Add or update package scripts so I can run the API with a simple command.
9. Create or update a file named api-build-notes.md explaining what you changed and how to run the server.

Please implement the code for me. After you finish, tell me the exact command to start the API and the HTTP requests I should use to test it. Include the method, URL, headers, and body for each request.

Start the API server.

Codex should tell you the exact command. It may be something like:

bun run dev

or:

bun run src/server.ts

Start the server and leave it running while you test it.

Test your API with the LMS HTTP tool or curl.

Open the LMS HTTP tool from your course tools area. It is called HTTP.

The tool path is:

/tools/http

Use the HTTP tool when your API has a public or tunneled URL that the LMS can reach. If your API is only running on your own computer at localhost, test with curl from your terminal instead.

If you want to test your local API with the LMS HTTP tool, open the Library guide named Cloudflared Quick Tunnel Setup. It shows how to create a temporary public URL for your local API.

For each request, choose the method, enter the URL, add any needed headers, add a JSON body when needed, and send the request.

In the examples below, replace <your-api-url> with the URL where your API is reachable. This might be a public tunnel URL, or it might be http://localhost:3000 if you are testing from your own terminal.

Your exact requests may differ depending on your API spec, but you should test all five routes.

Example:

Method: GET
URL: <your-api-url>/zones

Method: GET
URL: <your-api-url>/zones/1

Method: POST
URL: <your-api-url>/zones
Header: Content-Type: application/json
Body:
{
  "name": "Greenhouse",
  "description": "Food production and plant monitoring"
}

Method: PATCH
URL: <your-api-url>/zones/1
Header: Content-Type: application/json
Body:
{
  "description": "Updated zone description"
}

Method: DELETE
URL: <your-api-url>/zones/1

Use your actual IDs and field names if they differ from these examples.

The LMS HTTP tool also shows a matching curl command. You may copy that command into your terminal if you want to test the same request from the command line.

Save your test results.

Create a file named api-test-results.md.

For each route, include:

the tool you used, such as the LMS HTTP tool or curl
the HTTP method and URL
any headers or request body you sent
the response you received
whether the result matched your api-spec.md

Verify the database changed.

After creating, updating, or deleting a zone, inspect the database directly with SQLite.

Example:

sqlite3 habitat.db "SELECT * FROM zones;"

If your table has a different name, use your actual table name.

Add one short note to api-test-results.md explaining how you know the API changed the database.

Fix problems with Codex.

If a request fails, copy the exact error, command, and response into Codex.

Use a prompt like:

This API request failed.

Here is the request I sent:

[paste method, URL, headers, and body]

Here is the response or error:

[paste response]

Please inspect the Hono route, the SQLite query, and api-spec.md. Fix the implementation so it matches the API contract, then tell me what to test again.

Keep testing until all five routes work or Codex clearly explains what is still broken.

Write your reflection.

Create a file named student-reflection.md.

Answer these questions:

1. What zone routes did you design?
2. Which route creates a new zone?
3. Which route changes an existing zone?
4. Which route removes a zone?
5. What request body did you choose for creating a zone?
6. What response shape did you choose for a successful zone creation?
7. How did you verify that the API changed the SQLite database?
8. What did Codex implement for you?
9. What decisions did you make as the API designer?
10. What Git branch did you use for this lab?
11. What is one thing you would improve about your API if you had more time?

Required Deliverables

Your GitHub repository must include:

Your Hono API source code.
Your existing habitat.db file.
api-spec.md, your REST API contract.
api-build-notes.md, created or updated by Codex.
api-test-results.md, with HTTP requests and responses.
student-reflection.md, with your answers.
A public GitHub branch URL for your habitat-rest-api branch submitted to the LMS.

Submit Your Lab With GitHub

Before you submit, make sure you are inside your lab directory. The path should be:

~/labs/habitat-rest-api

Confirm you are on the lab branch:

git branch --show-current

You should see:

habitat-rest-api

Commit your work and push the branch:

git add .
git commit -m "Complete habitat REST API lab"
git push -u origin habitat-rest-api

Get the URL for your GitHub repository:

gh repo view --web

In your browser, switch to the habitat-rest-api branch on GitHub.

Submit the branch URL with your lab submission. It should look similar to:

https://github.com/<your-github-username>/<your-repo-name>/tree/habitat-rest-api