CSE 341: Web Services

W01 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 Part 1, you will learn how to move from a short feature description to a detailed technical specification (spec). You will follow a guided process that includes understanding the feature, researching background concepts, drafting a first spec, evaluating that spec, and producing an improved version.

Application Requirements

During this week's assignment, you will implement the feature described below.

This application is a web service that stores and returns book data. Each book record includes id, author, title, and publicationDate.

For this assignment, you will implement the following feature:

Writing a Detailed Specification

The first part of the assignment is to write a detailed specification (spec) for the feature you are implementing.

A detailed spec is a document that describes exactly what your API should do. It includes:

• The endpoints that are available
• The methods that are supported (GET, POST, PUT, DELETE)
• The input the API expects (headers, query parameters, body)
• The output that is returned (response body, status codes)
• The way errors are handled

Why write a spec first?

A written spec helps you think before you code. Many bugs happen when requirements are unclear. A short planning step can prevent hours of rework later.

A spec also helps communication. If you work with teammates, they can review the same document and ask questions before implementation starts.

A strong spec can also be given to an AI agent to implement. The more clear the requirements, examples, and constraints are, the more likely the AI is to produce useful code with fewer mistakes.

Even when you work alone, a spec acts like a checklist. It keeps you focused on the required behavior and helps you test the right things.

Activity Instructions

Understand the feature and identify the core behavior

The first step is to understand the feature and the core requirements.

Complete the following:

1. Read the feature description slowly and think about the required behavior.
2. Identify the key requirements. In this case they are to retrieve all books and retrieve one book by id.

Research the feature area

Next, learn about the technical area related to the feature so your spec is based on correct technical ideas.

As you think about the requirements, are there certain technical concepts you need to understand better? For example, you might need to research:

• How to design RESTful API endpoints.
• How to structure JSON responses for consistency.
• How to use HTTP status codes effectively.

With this in mind, before continuing, first, make sure you have completed all of the Week 01 learning activities. Then, ask AI follow-up questions where needed to make sure you understand these ideas and how they connect to the feature you will build.

Develop Version 1 of the spec

The next step is to develop a detailed spec that clearly defines the API behavior, data format, and expected responses.

Here is an example of a Version 1 spec for this feature:

# Books API Spec

## Purpose
Create a basic web service that returns book data.

## Data Model
Book fields:
- id: string
- author: string
- title: string
- publicationDate: string

## Endpoints
1. GET /books
- Returns all books.
- Response status: 200 on success.

2. GET /books/:id
- Returns one book with matching id.
- Response status: 200 on success.
- If no match: 404.

## Initial assumptions
- Data is stored in MongoDB collection named books.
- API returns JSON.

Evaluate Version 1 of the spec with guided questions

The next step is to review your spec to see if it is clear and to look for any security or performance issues.

Ask yourself following questions. Then, copy your spec into AI and ask it these questions as well.

1. Are there any bugs or short-sighted decisions in this specification?
2. Are there any security concerns that are missing?
3. Are there any parts of the current route design that might be slow?
4. Are any response examples or error behaviors unclear?

Here are some answers you might decide:

• Publication date format should be explicitly defined in responses.
• The API should not expose internal MongoDB error details to clients.
• List responses should return only required fields and use predictable ordering when needed.
• The spec should include concrete JSON examples for success and not-found responses.

Develop Version 2 of the spec

The next step is to develop Version 2 of the spec by improving Version 1 based on your evaluation findings.

The following is an example of Version 2 based on the clarifications mentioned in the last section:

# Books API Spec

## Purpose
Build a read-only Books API in Express with MongoDB storage.

## Data Model
MongoDB database: cse341-books-db
MongoDB collection: books

Book object:
- id: string (required)
- author: string (required)
- title: string (required)
- publicationDate: string in ISO 8601 date format (for example, "2021-08-17") (required)

## Endpoints
1. GET /books
- Description: Return all books.
- Success status: 200
- Error status: 500
- Success response body example:
[
  {
    "id": "b1",
    "author": "Maya Rivera",
    "title": "Patterns of Light",
    "publicationDate": "2021-08-17"
  }
]

2. GET /books/:id
- Description: Return one book by id.
- Success status: 200
- Not found status: 404
- Error status: 500
- Success response body example:
{
  "id": "b1",
  "author": "Maya Rivera",
  "title": "Patterns of Light",
  "publicationDate": "2021-08-17"
}
- Not found response body example:
{
  "message": "Book not found"
}

## Error Handling
- Do not return stack traces to clients.
- Return a simple message for 500 errors:
{
  "message": "Internal server error"
}

## Implementation Notes
- Use a MongoDB collection named `books`.
- Seed the collection with the book documents needed for testing.
- Use environment variables for the MongoDB connection.

## Out of Scope for Week 1
- POST, PUT, DELETE routes
- Authentication and authorization

What has changed?

Can you see the differences between Version 1 and Version 2 of the spec? Can you explain why Version 2 is improved?

Here are examples of changes and why they help:

• The data model is more precise and explicitly defines required fields.
• The endpoint definitions now include success and error behaviors.
• Specific JSON examples remove confusion for both success and not-found responses.
• Error handling is now clear and safer.

Next Step

Continue to Part 2 - Create the Plan.

Other Links:

• Return to: Week Overview | Course Home