A useful Java portfolio API should explain a rejected request as clearly as a successful one. Before adding another endpoint, write down the response contract for the endpoint you already have.
This is a fictional learning exercise, not production code or a claim about ScholarLogic’s systems.
Choose one small request
Imagine a library API that creates a book reservation. For this exercise, the request needs a book identifier and a borrower reference. Start with fake records and decide which fields are required, which values are allowed and which rules depend on the current database state.
Keep these decisions separate. A missing borrower reference is an input problem. An existing reservation may be a business conflict. A database outage is an operational failure. Returning the same vague “Something went wrong” message for all three makes the interface hard to use and the project hard to review.
Define outcomes before implementation
Use this proposed contract as a discussion starter, then adapt it consistently to your project:
| Case | Proposed result | What the reviewer checks |
|---|---|---|
| Valid new reservation | 201 with reservation identifier | One record created |
| Missing required borrower reference | 400 with a field error | No record created |
| Book does not exist | 404 with a stable error code | No record created |
| Reservation conflicts with the exercise’s rules | 409 with an explanation | Existing state preserved |
| Unexpected server failure | 500 with a safe general message | No internal details exposed |
These status choices are this exercise’s API design. Framework annotations do not create the whole contract automatically. Authentication and authorisation need their own cases in an application that uses them.
Make the response useful to the client
Give the response a stable machine-readable error code and a separate readable message. A field-validation response might identify borrowerReference so the interface can place help beside the relevant input. Avoid making client logic depend on the exact wording of a sentence.
Do not return stack traces, database connection strings or private record contents in a public error response. Keep any diagnostic reference safe and avoid treating it as permission to expose logs.
Check the validation path in your Spring version
Spring MVC supports validation for controller methods. Its official documentation distinguishes individual argument validation from method validation; the applicable exception can depend on the controller signature. Review both MethodArgumentNotValidException and HandlerMethodValidationException when designing consistent handling.
Use the Spring MVC validation reference for your installed version. This article deliberately does not provide a drop-in exception handler.
Demonstrate behaviour, not just annotations
Prepare a request and expected response for every row in the table. Check the status, response shape and database state. Include malformed input and an operational failure that you simulate safely in a development environment. Do not send test reservations to a real service.
A strong project README explains what the client should do next: correct a field, refresh a conflicting record, or try later after a temporary failure. It also states which behaviours have actually been tested and which remain planned.
Learners comparing practical Java projects can review ScholarLogic’s Java Full Stack course outline. Ask to see how a project handles rejected requests as well as its successful demo.
Prepared with AI assistance for ScholarLogic. All examples are fictional; no executable implementation or passing test result is claimed.
Top comments (0)