Shared Data Contracts

Most Web applications today must interact with the server in some way to get and send data, and this is typically done with the HTTP protocol. With Angular propelling TypeScript into mainstream Web app development, we have new opportunities for communicating with the server through strong typing over HTTP. For a long time, server-side languages like Java and C# have used strong typing to provide more control and confidence over data type alignment through data contracts.

A data contract is an assurance that data types between two systems, services, or in the case, the server and browser align. This can prevent numerous bugs and catch problems like case mismatches, misspelling, and changed attributes before they show up in production. This becomes even more helpful when using TypeScript tools to help autocomplete property names and view what properties are available without having to look through documentation.

API Contract with OpenAPI

For the server and client to communicate through data contracts, there must be a common agreement on how to format messages. Although multiple specifications have been developed for HTTP communication, Swagger developed one of the most popular specifications called OpenAPI.  OpenAPI provides a way to express an API which can be displayed for humans to read, or in JSON format for usage by tooling or other applications.

Swashbuckle is a middleware for ASP.Net Web API that automatically creates a swagger JSON file and user interface with very little work to implement.

Swashbuckle Setup

Simply install the Swashbuckle.AspNetCore package and then add the basic configuration in the Startup.cs file for .Net Core, :

Next, startup the .Net Core API and go to /swagger endpoint to view the Swagger UI. The generated data contract for the API will be at /swagger/v1/swagger.json.

Generated Tour of Herios API in Swagger UI

Generated Tour of Herios API in Swagger UI

Generating Angular Code from an OpenAPI Contract

Now that we have a generated swagger.json file available from our .Net Core API server, we make use of it with Angular and Typescript to generate not only the models but also the Angluar API module and services for use within our Angular application. After trying multiple OpenAPI TypeScript and Angular code generators, my favorite so far is ng-swagger-gen. The library is compatible with Swagger 2.0 and Angular 4.3+ and provides many great features including Angular module and service generation in addition to the models.

ng-swagger-gen Setup

To configure the swagger generator in a new Angular CLI application, first run:

npm i ng-swagger-gen

This will install the library. Add a new command to the package.json file under the scripts section  "api": "ng-swagger-gen -i http://localhost:30628/swagger/v1/swagger.json",.  Just be sure to change the path to the swagger JSON URL configured in the previous section. Finally, start the server API and run:

npm run api

Running the api command we just created will generate all the code necessary to call your API from Angular.

Under the Angular  src/app/api  you will now find the generated api module, models, services, and configuration file. Setting up new API module is as easy as including ApiModule in the app.module.ts imports. Now you can inject your newly generated HeroesService into any controller or other services that you’d like to make API calls from.

VSCode auto-completion using the generated Angular Service to get heroes

API Changes & Updating

APIs usually change over time and when the time comes that you need to update your API contracts, simply rerun the npm api command like previously done and any changes, both additions and deletions, will be reflected in the generated TypeScript. This is extremely valuable to teams because any API updates that break existing client-side code will become immediately apparent. Any data models that change because the API C# model changed will show up as an error when running the Angular CLI serve or build commands.

An error occurs in the case that the 'description' property is removed from the C# model and the npm api command is run again

An error occurs in the case that the ‘description’ property is removed from the C# model and the npm api command is run again


As applications grow and evolve, the need for background tasks and scheduled jobs becomes more of a necessity. This is especially true with microservice architectures and in dealing with eventual consistency and event-driven communication. .Net Core 2.0 has a new interface, IHostedService, which makes executing background jobs easier. When using the IHostedService interface you can register multiple hosted services that will run in the background of your web application.

The IHostedService interface looks like:

You may be thinking, “What’s the difference between a hosted service implementing IHostedService vs starting a background thread to run a task?” The difference is the hosted service will be started and stopped with the application. When starting a background thread, the thread cannot gracefully handle clean-up actions and will be killed when the application is stopped. The HostedServiceExecutor will handle the starting and stopping of the hosted services. This will allow for the hosted services to be cleaned up gracefully when the application is stopped.

When creating a hosted service, you could implement the IHostedService, but .NET Core 2.1 will include an abstract base class called BackgroundService. The BackgroundService will provide the common operations needed for background tasks such as cancellation tokens. If you are still on .NET 2.0, you can copy this base class into your repository. The code for the BackgroundService class is below.

Creating a Hosted Service:

A use case for a background task is having a task that “polls” a database to check for updates. When dealing with microservices, you might need to have local caches for some services. Local caches will contain copies of data from other services. This helps avoid chained API calls and dependencies on other microservices. One approach to keep the cache up to date is having clients subscribe to events that an application publishes (pub/sub). Another approach is having the applications journal the events (write the events to a database), and then the clients poll that journal database for new events. At AppRiver, the latter approach has proven to be a good fit when dealing with local cache synchronization. Below is an example of a hosted service polling a journaling database:

To keep this hosted service example simple, all of the logic around polling and updating the database is abstracted away in the JournalingUpdateService.

Once the application starts, the HostedServiceExecutor will kick off all the IHostedServices registered in the dependency injection in the Startup class (more on DI later). The JournalingManagerService’s ExecuteAsync method will be called. This will call the Update method on the JournalingUpdateService and then it will wait for 3 seconds before repeating. The service will continue to run until the token is canceled / application is stopped. The BackgroundService handles a lot of the work around service lives and if you are interested in more information on that, check out this blog post about the HostedService class.

The last part involves wiring up the hosted services. Each IHostedService will need registering (using dependency injection) in the ConfigureServices method in the Startup class (Note: multiple hosted services can be registered). This will look something like this:


The IHostedService interface is an easy way to run background tasks with a web application or host. Its main benefit is how gracefully it handles the clean up when the application is stopping. I would warn against overusing this feature and running a large number of tasks.

I’d recommend trying out the IHostedService interface and thinking about where it can be used in your architecture.

I’ve put together a sample repository to try out a hosted service. This repository uses an asynchronous messaging framework to journal integration events to a database. There are two microservices, Billing.API and Customer.API. The Billing.API keeps a local cache of the customer’s name. When the Customer.API updates the customer name it will publish an event to the journaling database. The Billing.API has a hosted service called JournalingManagerService which will poll the journaling database every three seconds to check for updated events.

Additional Resources

Alright, stop laughing. This is not an article about some bug-free Nirvana. Software will always have bugs as long as humans are producing it. We’re also not talking about bugs found during the quality control process. This article is about the attitude your software development team has toward the unfortunate—hopefully rare—bug that escapes from the lab, into production, and rears its ugly head in front of your users.


A zero-bug culture is the belief and resulting action adopted by a software team to ensure their production bug backlog remains empty.

The team needs to be fully invested. A top-down dictate will not be successful because the team will ultimately meet the letter of the law and not the spirit of a zero-bug culture. Culture is crucial because it’s a mindset, not a mandate.

Read More

I’ve always been interested in the names given to certain things in technology, or the technology itself, which has a long history.  What we use today draws meaning from that history, but sometimes it’s so far in that past that we’ve forgotten where it came from, or why it takes the form that it does today.  Sometimes we’ve moved so far from the beginning, that the originally intended meaning or process has been lost.  It just becomes “We’ve always done it that way” and it has too much momentum to change at this point.  Many of these things, if they hadn’t existed before, and were named or invented new today, would be totally different.  Let’s look at a few examples:

Read More

Three interns, and their views on how invaluable an internship is to a college student’s future, how to handle the process of an internship, and their personal experiences in AppRiver’s internship program.

internship salary chart

Chart statistics cited from

Erica Roachford

AppRiver’s internship program is a blessing for young aspiring professionals like myself. As an intern, you are treated like a real employee by being completely submerged in the culture. My coworkers are always helpful and upbeat, and they encourage me to contribute and ask questions. As an intern, I am working hands-on with every application, which allows me to apply the things I have learned in the classroom to real business situations. A plus is that I can shadow other departments, which is helpful in deciding where I want to take my career in software development. Being a full-time student, paid or unpaid, I believe internships are invaluable. The experience you gain is priceless. Internships open career opportunities that would be harder to obtain without one.

If you are an extremely motivated college student who is looking to gain experience with companies through an internship but have no idea where to start, visit your career services counselor on your college campus first. Start attending lunch and learn talks that teach resume writing, proper interview techniques, and insight into what to expect while interning with a company. Start networking through Social Media outlets such as LinkedIn, and begin searching job posting sites like Glassdoor,, and These are all great ways to stay up-to-date on current postings.

Going into an interview, you should have the same mentality you would if you were going up for an actual job interview (because it is). You should dress for success in professional attire. Be prepared with questions for the interviewers and have your resume with you to reference. Be confident, but admit when you do not know an answer. Being nervous is part of the process, but always remember that the interviewer is human, too, and they have a big decision to make in selecting the perfect candidate. Also, rejection is a part of the process, so be prepared for bad news. A great practice is to ask the hiring manager why you were not chosen for the position. Learning from your mistakes will make you a better candidate in the future. Happy interning!

Lucas Griffin

I’ve worked for a few companies in my life, had a few different interviews, and learned a great deal from each one. But I can honestly say that AppRiver shattered all the expectations I had for a career, and in the best way. Their internship program is extremely valuable and, without it, I wouldn’t know half of what I know now. It has given me great insight into what work is like for a developer and I would recommend everyone in college apply for this internship. In this post, I want to discuss some ways AppRiver stands out to me, and how the internship has helped me improve at software development.

The first thing I want to mention is the interview. I had a few interviews before this one and thought I could handle it, but then I found out that it was a panel interview. Panel interviews are terrifying (or at least they were in my imagination), but this was my first indication that AppRiver was different.

I felt the interview had the perfect balance of questions, ranging from coding, to questions about me as a person. This let me know that I wasn’t just a programmer to the company and it’s something that’s really stuck with me ever since. It gave me valuable interview experience and I feel that any interview down the road will be much easier for me.

Another way this internship has helped me improve as a developer is by letting me see the way developers work in a professional setting. In some of my earlier classes, I had teachers who counted off if the code wasn’t heavily commented and stated that lots of comments were important. When I started working at AppRiver, I saw that this wasn’t the case.

Sure, comments are important when there is some tough code to read, but relying on comments to explain code is a bad habit, and usually leads to ugly code. Without this internship, I wouldn’t know the importance of writing self-documenting code that helps improve programming ability and avoids bad names (function doesThing, var x = “stuff”, etc.).

All in all, this internship has been a great experience for me. It has allowed me to improve without the fear of failure since, anytime I make a mistake, no one is mad. I’m extremely glad that I get to continue my career with a company that offers such a great internship program!

Phil Hawkins

Applying for internships is one of the most important things you can do while pursuing a degree in Computer Science. Internships offer invaluable, real-world experience in the industry, which could help you stand out from the crowd when applying for full-time positions. Just getting into interviews can be extremely helpful, as having software engineering interview experience will help you be more comfortable in the future and to be more confident in your skills.

Getting my internship at AppRiver has been one of the most valuable learning experiences in the world of software engineering. When I first began working here, I had no idea what I was in for with AppRiver. Learning programming at my university was a much different experience than programming in the real world. Coordinating with various development teams and meeting deadlines is something they never prepare you for. During the first few weeks I felt overwhelmed with how much information I needed to learn to be productive. Having a mentor has helped me be more comfortable in my programming abilities.