SpanishByExample

SpanishByExample is a RESTful Web API that allows Spanish learners to collaboratively create and share example sentences which are meaningful to them.

Author: David Pasch
Date: 2026/03

About This Project

This repository contains a sample Web API developed as part of my personal portfolio. Its purpose is to demonstrate API design, backend architecture, and best practices in C# and ASP.NET Core.

Tech Stack

• C#
• .NET10
• ASP.NET Core 10 Web API
• SQL Server
• JWT Authentication
• xUnit, Moq, FluentAssertions
• GitHub Actions (CI)

Requirements

You need the following tools for running the project:

• Visual Studio 2026
• SQL Server
• Postman (for API testing)

Features

• User registration and authentication (JWT)
• Create vocabulary entries with examples
• Retrieve vocabulary with usage examples
• Input validation and error handling
• Layered architecture (API, Business, Data Access)

Setup

The following steps are necessary for setting up the project:

• First, you need to create an empty database on the SQL Server, e.g. spanish_ex

• Next, you need to configure the Web API through the appsettings.json file:

  • Set the database connection string.
  • Set a private key for signing the token during JWT user authentication.

• Finally, you setup the database.

  For this to work ensure that:

  • The connection string is set in appsettings.json.
  • You're in the Api project's root directory.
  • The Api project is both the Default project and Startup project.

  Then run the following command from the Package Manager Console:

Update-Database

That's it!

You're ready to try out the Web API.

Quickstart

Once you have setup the project and have a running Web API, you can do the following:

• Register a new user and login through the public endpoints /api/Auth/register and /api/Auth/login.
• Create a new vocabulary entry with usage examples through the protected endpoint /api/Vocabulary.
  • NOTE: You must provide at least one usage example.
• Retrieve a vocabulary entry with its usage examples through the public endpoint /api/Examples.

NOTE: The Web API currently only supports Spanish verbs in infinitive form for vocabulary entries.

You can find example requests in the Postman collection (see below).

File structure

The project repository contains the following files:

/database           
  /seed             # scripts to populate the database with sample data
  /tests            # scripts to test the database
/postman            # Postman files for API Testing
/src                # source code
/tests              # unit tests

Project structure

The Web API is realized as a three layered architecture. It consists of the following projects:

SpanishByExample.sln
│
├─ SpanishByExample.Core
│  ├─ Services
│  ├─ Commands
│  ├─ Entities
│  └─ Errors
├─ SpanishByExample.Api
│  ├─ Authentication
│  ├─ Controllers
│  └─ Dtos
├─ SpanishByExample.Business
├─ SpanishByExample.DataAccess
└─ SpanishByExample.Tests

The projects implement the following layers:

• The top layer is the Api layer which implements the interface to the user application.
• The middle layer is the Business layer which implements the business logic and shields the Api layer from the database communication.
• And finally, the bottom layer is the DataAccess layer which handles the communication with the database.

The SpanishByExample.Api project contains:

• Authentication: classes needed for implementing the user authentication.
• Controllers: controllers implementing the endpoints of the Web API.
• Dtos: DTOs used by the controllers to pass data from and to the clients.

The design of the layers is based on the Facade design pattern. The communication of information between the layers, i.e. data and errors, are conveyed in types specific to the layer in order to insulate the upper layers from the lower ones.

The SpanishByExample.Core project contains the interfaces and classes that are shared among all the other projects. It contains:

• Services: interfaces of the dependency-injected services.
• Commands: commands to specify the tasks the Business layer has to do.
• Entities: classes representing domain entities.
• Errors: custom exceptions for communicating errors from lower layers.

The SpanishByExample.Tests project implements the Unit tests that are executed as part of the CI pipeline, typically on Pull Requests.

Testing

This section describes the testing activities that were performed in order to ensure the quality of the product.

Unit Tests

Business logic and controllers tested with Regression tests at Component level.

Tools used:

• xUnit
• Moq
• FluentAssertions

System Tests

Manual end-to-end tests using Postman:

• User registration
• User authentication
• Vocabulary search
• Creation of vocabulary entries
• Error handling

Test Environment

The Test Environment consists of:

• ASP.NET Core Web API
• JWT authentication
• SQL Server
• Deployment using dotnet publish

API Testing

A Postman environment and collection are included in the postman/ directory.

Steps:

1. Start the API
2. Import Environment into Postman and fill out missing values
3. Import the Collection into Postman
4. Run the "Register" and "Login" requests to create and authenticate a user
5. Store the JWT Token in the Environment
6. Run the "POST" request of the Vocabulary folder to create an entry in the database
7. Run the "GET" request of the Examples folder to read the entry from the database

Future Improvements

• Integrate an external 3rd party dictionary service
• Implement additional use cases like example management for authorized users
• Add integration tests
• Dockerize the application