Getting Started

Overview

This repository, reference-architecture-api, is a core component of an overall reference architecture that I promote for building secure enterprise and Internet-scale web applications. The is API repository can be used as a template to build microservices in an efficient and repeatable way. There is no need to reinvent the wheel and many best practices are already baked into this solution.

This example API is built on the .NET Core and is cross platform compatiable. It can run locally on any platform that can host .NET Core and is specifically implemented to run within Linux-based Docker containers.

Quick Install

The following steps will quickly get you up and running and testing this API.

1. Install the dependencies (details below)
2. Fork the repository
3. Clone the forked repository
4. Run the build and test commands

   dotnet restore
   dotnet build

5. Manually run the unit and integration tests

   dotnet test

6. Run the application

   dotnet run -p src/Infrastructure.WebApi/

7. Manually test the application

   curl http://localhost:5000/api/ping

Or you can just copy and paste the above URL your browsers address bar.

Errors

If you experience errors, it is likely that you do not have all of the requisite dependencies installed. Please ensure that you do. Follow the instructions, below.

If it turns out that you do have all of the dependencies installed and you are still experiencing errors, please create a new Issue.

Install Dependencies

There are a number of depenedencies that must be installed locally on your development machine in order to get this application to build and run. The dependencies are detailed below, along with direct links that you can use to download them.

The following table lists the absolute minimum requirements for building and running the reference API.

Dependency	Description
.Net CLI	Command-Line Interface tool needed to compile and run the source code
MongoDB	Running database required to execute the application or tests in the local environment.
Docker	Must be installed and running in order to run the application entirely in Docker containers

Git SCM

Install Git SCM for your given platform. This will install the git bash command-line tool that has all of the environment variables arleady configured. There is also an option to install the environment variables for use with the standard Windows command-line or OSX Terminal.

Though they are not required, it may also be useful to install GitHub for Windows or GitHub for Mac.

.Net Command-Line Interface

You will want to install the dotnet-cli and associated tools. The build script used in this repository have a dependency on the .NET command-line tools.

MongoDB

There are a couple of different options for satisfying the MongoDB requirement.

1. You can download the MongoDB binaries and install directly onto your local development machine.
2. You can downlaod the official MongoDB Docker image and run that locally.
3. You can use a hosted docker service, like mLab or Azure's CosmoDB.

Docker

You will need to install Docker on your local development machine.

1. Install Docker for Windows
2. Install Docker for Mac

Fork the Repository

Navigate in your browswer to the reference-architecture-api repository. https://github.com/walterpinson/reference-architecture-api

Follow the GitHub instructions for Forking a Repository.

Clone the Fork

Navigate to your fork of the reference-architecture-api repository. Follow the GitHub instructions for Cloning a Repository.

Build / Test

You can manually build the API on your local host by running the following commands in a git-bash window, terminal window, or Windows command-line window after switching to the repository root directory.

dotnet restore
dotnet build

If you want to run the unit tests and the integration tests, issue the following commnand.

dotnet test

If you want to launch the API on your local host, issue the following command.

dotnet run

The dotnet command-line interface documentation is quite useful for those looking for command-line mastery.

Run

There are a number of scripts that can be used to expedite each aspect of the manual build process or tie them all together in order to get the application running in a Docker container.

Build and run the application stack

sh/runstack.sh

This command runs the API and the supporting MongoDb database server as Docker service stack.

Build and run the application as a docker container

sh/run.sh

NOTE: This approach still requires a running MongoDb database in the local environment.

This command deletes any existing containers, and rebuilds the source, rebuilds the docker image, and reruns the container. This is your go-to command. When you make some code changes and you want your running docker container to reflect those code changes, this is is the command that you run.

Build the source and publish the application

sh/build_app.sh

Build the Docker image from the published application

sh/build_image.sh

Run the Docker image as a container

sh/build_container.sh

Documentation

You can find further documentation detailing the concepts behind this reference architecture in the reference-architecture-api Wiki.