In this post we'll explore our options regarding how different services could communicate with each other. There is no code in this post, we'll just explore some different architectures and the trade-offs included with each one. In the end you can make up your own mind about your own specific domain. I have my preference for Govrnanza and in the next part we'll implement that strategy and get into some code.
So far we have a relatively simple ASP.NET Core 2.0 Web API that runs directly on the Windows operating system. But the next few posts in the series are going to need Docker. We'll be using Linux containers and looking at configuration, secrets management, and adding a second API. We'll be looking at using Docker Secrets, Docker configuration files, using Hashicorp Vault and creating our first Swarm with two services. So in this post we'll look at the built in Docker support in Visual Studio 2017, look at the various files that get added and what they do.
In the last post we added a short description of the API using markdown. The Description property of the Info class gets rendered at the top of the page above the list of actions.
In this post we are going to take that a bit further. One problem with putting documentation in your Swagger docs is that if you put a lot of detail there then you are forced to scroll down every time you view the Swagger UI of your API. This can get pretty annoying quick. So we'll look at a trick for adding as much detail as you want but avoiding the scrolling issue.
Swagger acts as both machine and human readable documentation for your APIs but also via the Swagger UI offers you a way of interacting with your APIs easily. We are going to embed a Swagger UI in our APIs that will load when you press F5 making it hassle free to test your API during development and testing.
We are going to add Swashbuckle.AspNetCore to our ASP.NET Core 2.0 API to create this embedded Swagger UI.
We are going to develop some APIs with ASP.NET Core 2.0 in this series so we need to decide what we are going to build. This series is enterprise focused but honestly the idea of building a regular enterprise system doesn't sound super fun. So we are going to kill two birds with one stone, we are going to build an API governance system. API governance is a topic for this series as it is vital in a large organisation, but it is also quite an interesting concept.
- API Series Part 1 - Let's Build Something
- API Series Part 2 - Documentation - Swagger
- API Series Part 2b - Add Non-Intrusive Markdown to Swagger UI
- API Series Part 3 - Adding VS2017 Docker Support
- API Series Part 4 - Secrets Management with Docker Secrets
- API Series Part 5 - Configuration with Docker Configs
- API Series Part 6 - ASP.NET Core 2.0 and Integration Testing
In this series we'll build a set of APIs with ASP.NET Core 2.0 in a cloud native, microservices architecture that can satisfy a long list of non-functional requirements.
So what does cloud native actually mean? It means that you don't know where your applications are going to run anymore. Your applications need to be able to work out how they are configured and integrate themselves into the wider system of services and start working. Why is that a desirable thing? Because it means that we can stand them up and down at will, without need for special system configurations. That means we can create copies of them for scaling out and we gain resiliency because when one copy of an application dies we just start up another one.