In our fast paced society, going on the web is part of the norm in our culture. We browse through our favorite websites to catch up on news or see what our friends are doing on Facebook. This allows everyone from different parts of the world to collaborate and network daily. One of the reasons why we have this today is because of web APIs. In this article, I'll walk you through how to build a web API with .net core.
A web API is a widely used technology where we can pass back data between client and server. In order to tie this back into our GIS world I will give an example of how graphic work designs can be a collaborative effort between two systems.
We can create a web service to hold endpoints that consist of logic to fetch, create, update, and delete resources to establish a set of rules for the external systems to consume. For example, system1 is creating an endpoint for system2 to get all work requests to be displayed onto system2's client application. This is a simple GET request where system2 can call system1's API to retrieve that data and it can be used to store or view on system2's application. In a practical case, system2's client application can now manipulate the data by adding graphic designs, then send some kind of data back to system1 to indicate that the graphic design is complete by calling its API to update that work request.
In this article, I will go over step by step instructions to set up a web API in which multiple systems can use to read or manipulate necessary resources for their specific needs. Keep reading for your startup guide to building web API, with screenshots and sample code.
Create a new folder in order to build the API project. In the integrated terminal from Visual Studio Code, type the following command:
dotnet new webapi
Follow up with the command to restore dependencies.
As you see from the screen shot below, you will have the bare minimum items needed to start the web api project.
We are given a csharp class called ValuesController.cs. This is a generic controller that holds the endpoints that external systems will call out to. The snippet below follows the architectural style of REST where it holds definitions of the most commonly used HTTP verbs.
In order to successfully communicate what endpoints are provided and what is needed in order to get the expected response. The host of the API should use a documentation tool to display the endpoint information. It is important to expose the route, query parameters, JSON request example, JSON response example, and a description of the endpoint's purpose. This is needed so that other developers who are building around the API from external systems can keep consistency and correctness of intended functionality. Restlet studio is an example of a tool which can provide API documentation.
Once we have built the API and the documentation, we can now publish this to IIS where it can be exposed to be used by other developers (external systems). Enter “dotnet publish”. This will compile the latest code into the bin folder where you can set your physical path in IIS. Make sure you have IIS set up properly to host your API. Also you must allow IIS_USRS to access the folder with the published dlls by navigating to properties and security.
A way to test these endpoints is to use programs like postman. Of course you can test simple GET commands through the browser, but having a program like Postman will allow you to test all HTTP verbs.
This is just a quick start up of getting APIs running on your machine. However, there are other topics that can help supplement your API which includes authentation, object relational mapping, MVC, and much more.