W02 Assignment: Part 1 - Develop the Specification
Overview
- Purpose: Complete the assigned portion of this week's project.
- Task: Follow the instructions below and submit the required work.
In Week 01, you built the first version of a Books API. This week, you will extend that API with full CRUD operations, add an authors collection, model a relationship between books and authors, and use Swagger to document and test the API.
In this part of the assignment, you will write a specification for the Week 02 Books API work. Unlike Week 01, the full spec is not provided for you. You will use the features and requirements below to decide the details.
Independence still needs detail
Making your own design decisions does not mean writing a vague plan. Your specification should be specific enough that another developer could implement and test your API without guessing what you meant.
Features
For this assignment you need to implement the following features.
Features
- Update your book data model to include a reference to an author ID (rather than the author's name directly), and then update your API to provide the remaining CRUD operations for books (create, update, and delete).
- Add an author collection that stores author ids, names, and birth years. Your API should provide all CRUD operations for this collection.
For all of these API methods you must have complete Swagger documentation so every book and author API route can be understood and tested from the browser.
Activity Instructions
Create Version 1 of your spec
Create a document named spec-week02.md. In that document, create a separate Version 1 specification for each feature. A complete Version 1 spec for the books feature is provided below. Copy it into your document, read through it carefully, and then create your own Version 1 spec for the authors feature using the same level of detail.
# Books API Week 02 Spec - Version 1
## Feature 1: Book CRUD Operations and Author References
### Goal
Update the existing Week 01 book API so book documents include a reference to an author and the API supports all CRUD operations for books. Every book route must be documented and testable in Swagger.
### Data Model
Book documents will be stored in the `books` collection.
Required book fields:
- `id`: string, required, custom id such as `b1`
- `authorId`: string, required, references the `id` field of an author document
- `title`: string, required
- `publicationDate`: string, required
Books will continue to use custom string ids instead of MongoDB `_id` values for route parameters.
### Relationship to Authors
Each book will identify its author with an `authorId` field. The value of `authorId` must match the custom `id` value of an existing author document.
When creating or updating a book, the API should reject the request with a `400` status code if the submitted `authorId` does not match an existing author.
### Routes
#### GET /books
Purpose: Return all books.
Success:
- Status code: `200`
- Response body: an array of book objects
Errors:
- `500` if an unexpected server or database error occurs
#### GET /books/:id
Purpose: Return one book by its custom id.
Success:
- Status code: `200`
- Response body: the matching book object
Errors:
- `404` if no book exists with that id
- `500` if an unexpected server or database error occurs
#### POST /books
Purpose: Create a new book.
Request body:
{
"id": "b4",
"authorId": "a1",
"title": "Example Book Title",
"publicationDate": "2026-01-15"
}
Success:
- Status code: `201`
- Response body: the newly created book object
Errors:
- `400` if a required field is missing
- `400` if the `id` already exists
- `400` if the `authorId` does not match an existing author
- `500` if an unexpected server or database error occurs
#### PUT /books/:id
Purpose: Update an existing book.
Request body:
{
"authorId": "a2",
"title": "Updated Book Title",
"publicationDate": "2026-02-20"
}
Success:
- Status code: `200`
- Response body: the updated book object
Errors:
- `400` if a required field is missing
- `400` if the `authorId` does not match an existing author
- `404` if no book exists with that id
- `500` if an unexpected server or database error occurs
#### DELETE /books/:id
Purpose: Delete an existing book.
Success:
- Status code: `204`
- Response body: none
Errors:
- `404` if no book exists with that id
- `500` if an unexpected server or database error occurs
### Swagger Documentation
Swagger must document every book route.
### Deployment Expectations
After implementation, the book routes must work locally and from the deployed Render application. The deployed Swagger page at `/api-docs` must allow someone to test every book route from the browser.
## Feature 2: Author CRUD Operations
TODO: Follow the example above to complete a spec for the authors feature.
Your author feature spec must answer these questions:
- What fields are required for an author?
- Which routes will exist for authors?
- What JSON body should clients send for create and update requests?
- What status codes and JSON responses should each route return?
- What should happen if a client tries to delete an author who still has books?
Custom ids and MongoDB _id
Week 01 used custom id values such as b1 so route testing would be easier. You should continue that approach in Week 02 for authors as well.
Evaluate your spec
The next step is to evaluate your specification to see if it is clear, safe, and realistic to implement.
Ask yourself the following questions. Then, copy your spec into AI and ask it these questions as well.
- Are there any bugs or short-sighted decisions in this specification?
- Are there any security considerations that are missing?
- Are there any efficiency concerns with the current endpoint design?
- Are any response examples or error behaviors unclear?
Create Version 2 of your spec
Revise both feature specs based on the response you get from AI. Version 2 should be specific enough to become your implementation checklist.
Next Step
Continue to Part 2 - Create the Plan.
Other Links:
- Return to: Week Overview | Course Home