A small REST API project: validation, errors and tests

A small API can reveal more about your understanding than a large application copied from a tutorial. The useful question is whether you can explain its behaviour when a request is valid, incomplete, repeated or unexpected. Building those decisions into a modest project gives you something concrete to discuss and test.

Use a fictional reading-list service as your learning exercise. It stores book titles and a reading status. Keep it local, use invented data and choose a language you already understand. This guide defines a practice contract; it is not a complete production architecture or a prescription for a particular framework.

Describe the resource before writing handlers

Write down what one book record means in this project. For example, it could have a server-assigned identifier, a title and a status such as planned, reading or finished. Decide which fields are required and which values are allowed. These are your design choices for the exercise, not universal rules for every reading application.

Then explain the operations you want: list books, fetch a book, add one and change its status. Avoid expanding into recommendations, payments or social features before those basic behaviours are clear. A narrow scope makes failures easier to understand and tests easier to relate to the contract.

Decide what the client is allowed to send

Separate input fields from fields the server controls. A client may propose a title and status, while the server creates the identifier. Decide how to handle unexpected fields, blank text and a status outside the allowed set. Document the decision so your tests can check it consistently.

Do not rely on a browser form to enforce these rules. A request can reach an endpoint without passing through that form. Check input at the server boundary before saving it. If you trim surrounding spaces, make that behaviour explicit; avoid silently changing meaningful content in ways the client cannot predict.

Give failures a useful shape

An error response should help the caller understand what happened without revealing internal details. For this exercise, choose a consistent response structure with an error identifier and a short explanation. A validation error can identify the field that needs attention. An unexpected server failure should not return a database connection string or a full internal stack trace.

MDN's HTTP reference distinguishes successful responses, client errors and server errors. Its status descriptions include 201 for a newly created resource, 400 for a request the server cannot process because of a perceived client error, 404 when the requested resource is not found, and 500 for an unexpected server condition. Match your response to the behaviour you actually implement.

Do not choose a success status merely because the handler finished running. If saving the record failed, returning a success message creates a misleading contract. Equally, a missing resource should not be disguised as an empty successful record just to simplify the interface.

Make a test table before implementation

Turn the contract into a short list of examples. For the fictional service, your table could cover:

• A valid title and allowed reading status create a record.
• A missing title produces a documented validation error.
• A blank title is handled according to the stated rule.
• An unsupported status is rejected without saving a partial record.
• Fetching an unknown identifier produces the chosen missing-resource response.
• A controlled storage failure does not claim that a record was saved.

Record expected behaviour before running each case. Otherwise it is easy to accept whatever the implementation happened to do. Keep the test data deterministic enough that another learner can reproduce a failure and understand the result.

Test state as well as the response

A response body is only part of the evidence. After a successful create request, check that the new record can be read back. After an invalid request, check that the store did not gain an incomplete record. When an update fails, confirm that the previous valid value remains intact.

For a local exercise, an in-memory store can make these relationships easy to inspect. Explain that restarting the application clears that store. If you later use persistent storage, add tests for the new behaviour rather than assuming a database automatically makes the application reliable.

Ask what repeated requests mean

Send the same valid create request again and observe the result. Does your exercise create another record? Does it reject a duplicate? Either choice needs an explanation tied to your design. Do not quietly add a uniqueness rule for titles if different books or editions should be able to share one.

You do not need to solve every distributed-systems problem in a first project. You do need to recognise that a client retry can affect state. Describe the current behaviour and what would need further design before the endpoint supported an important real-world workflow.

Keep the learning environment separate from production

A local service using fictional data is not ready for public use simply because its tests pass. Authentication, authorisation, abuse controls, operational logging and deployment configuration require separate design. State those omissions rather than adding untested labels such as secure or enterprise ready.

If you later add users, test access boundaries deliberately. One user's identifier must not become a way to read or change another user's records. Keep that as a separate extension with its own contract and tests so you can see what changed from the simpler exercise.

Use AI suggestions as proposals

An assistant can suggest test cases or explain an unfamiliar response. Check those suggestions against your chosen framework's current documentation and the contract you wrote. Do not accept code solely because it runs once. Ask yourself which behaviour each condition protects and what a failing test would demonstrate.

Avoid submitting private credentials or real user records as debugging examples. A small fictional request and a clear description of the failure are usually better learning material. Preserve the tests that caught a mistake so the next edit cannot silently reintroduce it.

Common questions

Which language should I choose?

Use one you can already read and debug. The point is to understand request handling, validation and state changes. Learning a framework and a new language together can make it harder to identify why a test failed.

Do I need a database immediately?

No. Start with a clearly documented local store if that helps you understand the contract. Add persistence as a deliberate extension and update the tests and documentation to reflect it.

What should I show when explaining the project?

Show a valid request, a rejected request and the corresponding state checks. Explain one design tradeoff and one unresolved limitation. That provides more evidence of understanding than showing only a successful screenshot.

Book a Coding Bytes demo to discuss your starting point and the programming or web-development path that fits the work you want to practise.

Source: MDN: HTTP response status codes. The reading-list contract and test cases are an original illustrative exercise.