2. Getting Started

Welcome to the getting started tutorial. Here you will learn how to create your own API using SAPI.

What are we building today?

You will create an API for servers to add themselves to a database, and allow clients to retrieve information about servers.

Prerequisites

• Basic knowledge of C#
• (optionally) REST Client (Postman, Insomnia)

Step 1 - Create a new console application.

I'm using JetBrains Rider, but the process is mainly the same: I recommend using .NET 6.0 SDK, but it should work on 5.0 as well.

Step 2 - Install SAPI

Install steps for Rider: View -> Tool Windows -> Nuget -> search for SAPI -> + Install steps for Visual Studio: Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution... -> Browse -> SAPI -> Install

Step 3 - Initialize SAPI

In your main method, create a new instance of Server, and at the end of the function, call Start() on this instance of the Server.

// Program.cs
using SAPI;

namespace MyAPI;

public class MyAPI
{
	public static void Main()
	{
		Server sapi = new();
		
		// Leave some space here - we will come back here later
		
		sapi.Start();
	}
}

If we start the application now and try to send a request to any endpoint, we would get 404 Not Found, because there is no endpoints to point to.

Step 4 - Create your first endpoint

Right-click your project, and create a new folder Endpoints, in which create a new file GetServers.cs. Make a public class GetServers that inherits from `IEndpoint.

// Endpoints/GetServer.cs
using SAPI.Endpoints;

namespace ServerAPI.Endpoints;

public class GetServers : IEndpoint
{
	
}

After doing so, your IDE would throw an error Interface member is not implemented.... To solve that right-click your class name and choose Show Context Actions/Quick Actions and Refactorings and choose Implement missing members/Implement interface. Fill the properties to look like this:

// Endpoints/GetServer.cs
using System.Net;
using SAPI.Endpoints;
namespace ServerAPI.Endpoints;

public class GetServers : IEndpoint
{
	public string url { get; } = "get-servers";
	public Method method { get; } = Method.GET;
	public void Task(ref HttpListenerRequest request, ref HttpListenerResponse response, Dictionary<string, string> parameters)
	{
		
	}
}

For now fill the Task() method to respond with an HTML page saying Hello, World!.

// Endpoints/GetServers.cs
using SAPI.Utilities;

// ...

public void Task(ref HttpListenerRequest request, ref HttpListenerResponse response, Dictionary<string, string> parameters)
{
	Utilities.HtmlResponse("Hello, World!", ref response);
}

Now we need to add(mount) this endpoint to our server.

// Program.cs
using SAPI;
using ServerAPI.Endpoints;

namespace ServerAPI;

public class ServerAPI
{
	public static void Main()
	{
		Server sapi = new();

		sapi.MountEndpoint(new GetServers());
		
		sapi.Start();
	}
}

If we now run the application and send a GET request on get-servers route, we should see a web page saying Hello, World!.

Step 5 - Create a mock database

Because it is a SAPI tutorial, not a database tutorial, for our database we will be using a basic list of our model class. Create a model for our data.

// Models/Server.cs
namespace ServerAPI.Models;

public class Server
{
	public string Name { get; }
	public string Message { get; }
	
	public Server(string name, string message)
	{
		Name = name;
		Message = message;
	}
}

Now create a service for managing our data.

// Services/Database.cs
using ServerAPI.Models;
namespace ServerAPI.Services;

public static class Database
{
	private static List<Server> servers = new();

	public static List<Server> GetServers() => servers;
	public static void AddServer(Server server) => servers.Add(server);
}

Step 6 - Create a new endpoint that will take provided data, and store it on our database.

// Endpoints/AddServer.cs
using System.Net;
using SAPI.Endpoints;
using SAPI.Utilities;
using ServerAPI.Models;
using ServerAPI.Services;

namespace ServerAPI.Endpoints;

public class AddServer : IEndpoint
{
	public string url { get; } = "add-server";
	public Method method { get; } = Method.POST;
	public void Task(ref HttpListenerRequest request, ref HttpListenerResponse response, Dictionary<string, string> parameters)
	{
		Utilities.JsonFetch(out Server server, ref request);
		Database.AddServer(server);
	}
}

If you were wondering what Utilities.JsonFetch() does, it takes the content of the body from the POST request and maps it to our model.

Remember to add our new endpoint to Program.cs.

// Program.cs

// ...
public static void Main()
{
	Server sapi = new();

	sapi.MountEndpoint(new GetServers());
	sapi.MountEndpoint(new AddServer());
	
	sapi.Start();
}

Step 7 - Alter the contents of our first endpoint to return all records from our database.

// Endpoints/GetServers.cs
using System.Net;
using SAPI.Endpoints;
using SAPI.Utilities;
using ServerAPI.Services;
using Server = ServerAPI.Models.Server;
namespace ServerAPI.Endpoints;

public class GetServers : IEndpoint
{
	public string url { get; } = "get-servers";
	public Method method { get; } = Method.GET;
	public void Task(ref HttpListenerRequest request, ref HttpListenerResponse response, Dictionary<string, string> parameters)
	{
		List<Server> servers = Database.GetServers();
		Utilities.JsonResponse(servers, ref response);
	}
}

Again, we are using a utility method(Utilities.JsonResponse()) that as the name suggests will send the client our model in JSON form.

Step 8 - Check our results

Start up your project, and in your REST client of choice send a few POST requests on http://localhost:8000/add-server with JSON body.

Now send a GET request to http://localhost:8000/get-servers.

Summary

That's it - you have created your own API with SAPI. With your new knowledge, you can create an API for your applications.