CS375: Software Engineering - Objects/API Summary Report (100 Points)

Assignment Goals

The goals of this assignment are:
  1. To prepare an Objects/API Summary that incorporates all collected software requirements in abstracted and independent software modules

Background Reading and References

Please refer to the following readings and examples offering templates to help get you started:

The Assignment

The Objects/API Summary (formerly called the Design Report) is the second of the four graded project documents (Requirements, Objects/API Summary, Test Plan, and User Manual). It is a catalog of the things your system is made of – the classes/objects, the API endpoints or microservices, and the data schema – and how your requirements map onto them. Think of it as the document a new developer would read to learn what exists in your system and where each responsibility lives.

In your Objects/API Summary, include a summary of your project goals and requirements from the prior report.

Then, for each requirement, specify a software design (either a microservice, or design pattern) that accomplishes that requirement in a modular, abstract, and/or isolated way.

Each method or microservice should include a list of pre- and post-conditions that will serve as your unit tests and acceptance tests to be discussed later in subsequent plans. List each of these methods within your class or microservice design along with a UML diagram describing each. You should specify which requirements keys each method, class, or microservice accomplishes. If you find that a particular code module attempts to accomplish too many requirements, this may be a sign that you should consider breaking this design into smaller components. Provide a schema for any database or cloud data storage.

API Endpoint Summary

If your system exposes a web API (most projects do), summarize every endpoint in a table so that the entire surface of your system is visible at a glance, for example:

Method Path Auth Required? Request Body Response Requirement(s)
POST /auth/login No {username, password} {token} R1
GET /notes Yes (JWT) – array of notes R3
POST /notes Yes (JWT) {text} created note R4

For a non-web project, provide the equivalent: a table of public classes and methods with their signatures, callers, and requirement keys.

Use Case Traces

Finally, for each requirement, show a flowchart that describes the trace through the services and components of your software system that are exercised by that requirement. Ideally, this will be a relatively small trace for each requirement. If your system follows the MVC pattern, a route-to-controller-to-model trace table is an effective format.

Design Review Checklist

Before submitting, review your design against this checklist (and note in the document that you have); these are the mistakes most often caught in review:

  • Default values live in the model or controller, never the view. For every field the user does not consciously choose (creation timestamps such as createDate, record IDs, owning user, initial status), your schema or controller supplies the value – for example createDate TIMESTAMP DEFAULT CURRENT_TIMESTAMP in the schema, rather than a value posted from a form. See the MVC activity’s design guideline for the bad-vs-good example. Identify each such field in your schema and state which layer supplies it.
  • Every requirement key appears next to at least one class, method, or endpoint (and vice versa: no orphan components with no requirement).
  • Each component has one job: no class or service accomplishes an unrelated cluster of requirements.
  • Sensitive routes name their guard: any endpoint marked “Auth Required” identifies the middleware or check that enforces it.
  • UI color palette is specified and accessible: your design names the palette (hex codes) allocated by the 60-30-10 rule, your body text/background pair meets the WCAG AA contrast ratio of at least 4.5:1 (record the computed ratio), and no meaning in the UI is conveyed by color alone. See the GUI activity’s color section for the tools and the math.

Website

Include your Objects/API Summary on the project website.

Submission

In your submission, please include answers to any questions asked on the assignment page, as well as the questions listed below, in your README file. If you wrote code as part of this assignment, please describe your design, approach, and implementation in a separate document prepared using a word processor or typesetting program such as LaTeX. This document should include specific instructions on how to build and run your code, and a description of each code module or function that you created suitable for re-use by a colleague. In your README, please include answers to the following questions:
  • Describe what you did, how you did it, what challenges you encountered, and how you solved them.
  • Please answer any questions found throughout the narrative of this assignment.
  • If collaboration with a buddy was permitted, did you work with a buddy on this assignment? If so, who? If not, do you certify that this submission represents your own original work?
  • Please identify any and all portions of your submission that were not originally written by you (for example, code originally written by your buddy, or anything taken or adapted from a non-classroom resource). It is always OK to use your textbook and instructor notes; however, you are certifying that any portions not designated as coming from an outside person or source are your own original work.
  • Approximately how many hours it took you to finish this assignment (I will not judge you for this at all...I am simply using it to gauge if the assignments are too easy or hard)?
  • Your overall impression of the assignment. Did you love it, hate it, or were you neutral? One word answers are fine, but if you have any suggestions for the future let me know.
  • Using the grading specifications on this page, discuss briefly the grade you would give yourself and why. Discuss each item in the grading specification.
  • Any other concerns that you have. For instance, if you have a bug that you were unable to solve but you made progress, write that here. The more you articulate the problem the more partial credit you will receive (it is fine to leave this blank).

Assignment Rubric

Description Pre-Emerging (< 50%) Beginning (50%) Progressing (85%) Proficient (100%)
Requirements Cross-Reference (25%) The Objects/API Summary is missing references to several requirements The Objects/API Summary incorporates most requirements The Objects/API Summary incorporates all requirements The Objects/API Summary incorporates all requirements in a cross-referenced manner
Separation of Concerns (25%) The proposed design does not isolate concerns into software components The proposed design separates requirements into a set of concerns which are mostly captured by a few loosely coupled components The proposed design separates requirements into a set of concerns which are captured by a few loosely coupled components The proposed design separates requirements into a minimal set of concerns which are captured by a few loosely coupled components
Data Schema (25%) The data model does not support the proposed software design The data model supports the proposed software design following a major revision The data model supports the proposed software design except for a few minor suggestions The data model is appropriate for the proposed software design
Use Case Traces (25%) Use cases or user stories are not traced through the software components Some use cases or user stories are traced through the software components to ensure they are adequately designed and isolated Most use cases or user stories are traced through the software components to ensure they are adequately designed and isolated Each use case or user story is traced through the software components to ensure they are adequately designed and isolated

Please refer to the Style Guide for code quality examples and guidelines.