Build a private bookmark API with ownership and version checks

Application background

Ana finds an article on her phone and taps Save. Later she opens the learning portal on her laptop and expects to find the same link. The portal therefore needs to store bookmarks in a database, rather than only in one browser.

Each bookmark belongs to one person. Ana should see her own links, and Ben should see his. Another problem appears when Ana leaves the same bookmark open on two devices and edits both copies.

Example walkthrough

A version is a number attached to a saved record. Checking it before an edit prevents an older browser view from silently replacing a newer change.

Sizing that affects this decision

10,000 users with 20 bookmarks each means 200,000 records. At an assumed 1 KiB of metadata per record, that is about 195 MiB of raw data before indexes and backups. The initial target of 100 peak reads/s and 20 writes/s supports starting with one regional database and measuring it. It does not, on its own, justify adding a cache.

These are exercise assumptions. The estimation reference explains the units and approximations. They do not establish the local demo's measured capacity.

Your assignment

Deliver: Build endpoints to save, list and edit private bookmarks. Keep the records across restarts, enforce their owner and report when an edit is based on an old version.

Required behavior: POST /bookmarks returns 201 and a version. GET /bookmarks returns only the authenticated owner’s rows. PATCH /bookmarks/{id} requires expected_version and returns 409 on conflict. Sharing is a later feature.

The required first milestone is a working local implementation of the behavior above. The numbered implementation steps define the scope. The cloud architecture is a later extension, not something the starter has already provisioned.

Get the code and run the supplied example

The code is in the public junior-to-staff repository. Install Git and Python 3.12+. No AWS account or Python packages are required for this first run. If you already have a checkout, use it and skip cloning.

git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/architecture-starts/bookmark_service.py

Supplied file: examples/architecture-starts/bookmark_service.py. You can also read or download the source here (download file, source below).

"""Local mechanism demonstration for bookmark-service. No AWS resources are created."""
import sqlite3
c=sqlite3.connect(':memory:')
c.execute('CREATE TABLE bookmarks(owner TEXT,id INTEGER,title TEXT,version INTEGER,PRIMARY KEY(owner,id))')
c.execute("INSERT INTO bookmarks VALUES ('ana',7,'Original',3)")
for owner,title,version in [('ben','Unauthorized',3),('ana','Phone edit',3),('ana','Laptop edit',3)]:
    changed=c.execute('UPDATE bookmarks SET title=?,version=version+1 WHERE owner=? AND id=7 AND version=?',(title,owner,version)).rowcount
    print(owner,title,'saved' if changed else 'not found or version conflict')
print('Final:',c.execute('SELECT * FROM bookmarks').fetchall())

This program is a mechanism demonstration: it runs the small scenario in one process and prints the result. It is not an HTTP service, a complete application, or an AWS deployment. A successful run demonstrates this mechanism only. It does not establish the workload or failure guarantees of the application you will build.

Example output from the supplied run:

Generated IDs and timestamps may differ. Compare the state transitions and outcomes.

ben Unauthorized not found or version conflict
ana Phone edit saved
ana Laptop edit not found or version conflict
Final: [('ana', 7, 'Phone edit', 4)]

Set up your implementation workspace

Create work/bookmark-service/ in your checkout (or use a separate repository). Copy the supplied mechanism into that directory as mechanism.py, then extract its state transitions into functions you can call from your implementation. The record and module names below describe what you must implement. They are not a promise that files with those names already exist. Keep a README.md beside your implementation with its exact run commands and observed results.

Local components and state to implement

This table names the records, interfaces or decision inputs for your deliverable. Unless a name is explicitly linked to supplied source above, it is something you create. Implement the local state transitions first, then connect the HTTP, storage or worker boundaries required by the steps.

Implement the assignment

1. Create and list one private record

Implement api.py with create/list routes and a trusted request context containing the authenticated subject. In store.py, scope both lookup and update by owner. Save a URL without fetching it. An unavailable title service must not lose the bookmark. Show Ana’s list and Ben’s empty list for the same ID.

2. Preserve a client’s edit

Keep expected_version and the user’s unsaved draft in the browser. Commit UPDATE ... WHERE owner_id=? AND id=? AND version=?. Zero affected rows require a fresh read to distinguish missing from conflicting under your disclosure policy. The losing client keeps its draft and sees the latest saved version.

3. Make create retries safe

Commit the bookmark and operation result in one transaction. Compare a canonical payload hash when a request ID reappears. Crash after commit but before replying, then repeat the same request and show the original ID. Retain operation IDs for the documented retry window.

4. Add the cloud adapter

Map owner to the DynamoDB partition and bookmark ID to the sort key. Use a conditional version update and strongly consistent reads for the immediate post-write list. Keep the local SQL and cloud code behind the same store interface. Add cursor pagination with a stable ordering before creating a large inventory.

Demonstrate the completed local result

Handoff: In your implementation README, include the start command, one successful operation, the failure case above and the resulting stored state or decision. State which dependencies are simulated. Someone with a fresh checkout should be able to reproduce this without your chat history.

Workload assumptions and capacity decisions

These are constructed exercise assumptions. The stated workload is a design target. The local demonstration does not establish that throughput. Use the estimation constants to check units before choosing capacity.

Map the local implementation to AWS

Deployment status: local only. Running the supplied command creates no AWS resources and configures no cloud connections. The diagram is a proposed deployment of the completed application. Each box needs either a deployed runtime, a provisioned service or an explicitly external dependency.

Read the diagram by following the arrows from the entry point: application code accepts the request or event, the state owner commits it, and any worker produces the later result. The table ties those roles to code and adapter work. Multiple boxes do not imply multiple Python files already exist.

DynamoDB is a good fit for owner-keyed lists and conditional edits. PostgreSQL remains a simpler choice when sharing and relational queries dominate. Cognito authenticates the caller. Application code still decides who owns each record.

Provision resources, then connect the application

Use one disposable AWS environment for the cloud exercise. Put the named resources in infra/template.yaml or your existing IaC tool, pass resource IDs through configuration, and scope each runtime role to its own tables, buckets and queues. The diagram is a design to implement. It is not a claim that these resources have been deployed. Record the commands you used to deploy and remove the exercise resources.

For concrete provisioning commands, configuration wiring and cleanup, use the AWS foundation guide. It includes a deployable table/queue/object-storage foundation and explains which application and service adapters you still implement.

A provisioned queue or table does not make the local program use it. Configure resource IDs in the deployed runtime, replace the local adapter, and replay the same successful and failing operation against that runtime. Record the deployed commit and observable result, then remove the disposable resources using your infrastructure tool.

Extend the design after the baseline works

Worked follow-up: Revoke a shared bookmark even when its content is cached

Alice shares item 41 with Bob, then withdraws the share. A cached copy can still contain the correct bookmark text while carrying an obsolete access decision. Content freshness and permission freshness now have different owners.

Revised architecture. Follow the changed responsibility and failure path below. This is a design to implement. The supplied local example does not provision these components.

What to implement. Add a share record with token hash, item ID, expiry and revoked state. In the read handler, check the share against authoritative state before serving cached content. Keep private responses out of browser and CDN response caches. For the immediate-revocation contract, deny new reads when the permission store cannot be reached. A response already delivered cannot be recalled. On AWS, keep this decision in the API handler with a suitable consistent database read. CloudFront may still cache the static app.

Walk through the result. Warm token S by reading item 41. Revoke S, leave the content cache untouched, then repeat the same request. It must be denied. Document the ordering point: revocation completed before the new authorization check. Your deliverable is the share schema, revised read path and this request transcript.

Add revocable sharing only after private reads work. State the authorization decision point, recheck it on cache hits, and demonstrate that a revoked share token cannot authorize a new response. At ten times the read rate, measure query latency and hot owners before adding a cache.