Made withASP.NET CoreClip

Making a Simple API | ASP.NET Core 101 [7 of 13]

D

dotnet

Creator on the ASP.NET Core channel

Watch on YouTube ↗

169K viewsSep 23, 20199:32 runtime

Learn how to create a simple web API in ASP.NET Core to serve data as JSON. This tutorial covers the basics of turning your web application into a web service that other applications, like mobile apps, can consume. Explore fundamental concepts such as defining API endpoints in…

Chapters

#aspnetcore#clip#frameworks

Introduction to Web APIs

An API (Application Programming Interface) allows different applications to communicate in a formalized way.
Web APIs, or web services, expose data over the internet, typically for consumption by other applications (e.g., mobile apps).
Instead of returning HTML for a browser, web APIs usually return data in a machine-readable format like JSON (JavaScript Object Notation).

Creating a Simple API Endpoint

API endpoints are configured in the startup.cs file within the Configure method's app.UseEndpoints() block. You can create a simple, low-level GET endpoint using the endpoints.MapGet() method.

Note
This manual approach is useful for understanding the fundamentals. More advanced and maintainable methods, like using API Controllers, are often preferred for real-world applications.

Endpoint Implementation Example

The following demonstrates creating an endpoint at the /products URL that returns a list of products as JSON.

Route Definition: Define the path and the logic to execute. endpoints.MapGet("/products", context => { ... });
Service Retrieval: Inside the lambda, manually access registered services from the application's service container. var productService = app.ApplicationServices.GetRequiredService<JsonFileProductService>(); var products = productService.GetProducts();
JSON Serialization: Convert the C# object collection into a JSON string. var json = JsonSerializer.Serialize<IEnumerable<Product>>(products);
Response: Write the JSON string back to the client as an asynchronous operation. return context.Response.WriteAsync(json);

Important `using` Statements

Visual Studio's "light bulb" helper is useful for adding required using statements for new types and methods you introduce.

System.Text.Json: Required for JsonSerializer.
Microsoft.AspNetCore.Http: Required for context.Response.WriteAsync.
YourApp.Models: Required to reference your Product class.

Testing Your API

After running your application, you can test the endpoint by navigating to its URL (e.g., https://localhost:5001/products).
The browser will display the raw JSON string.

Tip
Browser extensions like JSONView can automatically format raw JSON, making it much more readable for humans during development and testing.

Why Build a Web API?

We're about halfway through our ASP.NET 101 series. Feeling good. We've got a good looking website, we think, it's got some CSS and some HTML. It looks somewhat attractive to best of our ability. We've also got our cards. We hover over them. We're using Bootstrap for a lot of this. This data is coming out of a JSON file, but again it could come out of anywhere. In fact, this data could have come out of like a web service from someone else's web service that we would call.

Sure can.

Or someone could call us, and we're a web service.

Yeah, or what if it's just we want to maybe take this site mobile.

That's a really good point. We could make a mobile website, or we can make a Xamarin web app, and then make a web API that is going to provide these products as a service to someone else. Now, when you're doing that, you're not returning HTML, you're returning JSON.

Yes.

Your data could come from anywhere, but JSON is that format. So why don't we make a tiny simple web API, and then in the next video, we'll make it even more interesting and more complicated.

API Fundamentals and JSON Serialization

Okay. So you used API, I don't like abbreviations.

Yeah. So API, so Application Programming Interface, and that's the ability to go and call another thing in a formalized way. So everyone got together on the internet one day and decided that JavaScript was the way, and JSON, the JavaScript Object Notation, is a good way to express things. So we have a list of products, and if you remember.

It's a service too.

It is. That's a great point, it is a service. So if you remember, you had me making, where is it? There we go. You had me make this product. So that's the C Sharp class, or the shape of our product. We want to go and return that as JSON.

Good.

We want to basically make it so you go to our website, slash products, and it returns as JSON. Remember at the very beginning of the first video there, you had me do a JSON serializer.

Yes.

That's going to come in useful in this one, isn't it?

I think it will.

Let's find out. So the ability to be able to serialize JSON, or be able to serialize C Sharp into JSON is super interesting.

It is writing it back to JSON.

Configuring Endpoints in startup.cs

Now, right now, if I go to My App, and I say slash products, nothing happens.

What is that about?

Yeah, well, it's a big fail.

Yeah.

If I hit "Slash Privacy", I get a privacy policy page.

That was good.

Yeah. If I go over here, you can see I've got a privacy page. I've got my index, which is my default. I don't have a Products, but do I need a Products page? Do I need a Products end point, a place to land when you say slash privacy?

Well, apparently, in the startup file that some of us tend to ignore such as myself, there is a spot where you can insert additional endpoints.

There absolutely is. This endpoint of where a URL turns into some work is an endpoint and ASP.NET. You can see here that by default, again, this is a default, and you mentioned that you don't really look in startup.js. Most people don't need to because you get it configured, and then you spend most of your time making pages. We're going to do it in two steps. We're going to do an endpoint of our own that's custom, and then afterwards we'll do it another way. So here, we see that there's an endpoint, and then we say Map Razor Pages. It is because of that line that slash privacy and slash nothing actually works. We've also got an error. It looks like as well.

Yeah.

Okay. So it turns out you can say endpoints. and look, you can map all kinds of stuff; map this, MapControllers, MapDelete, MapFall, my goodness. Well, you can MapGet.

Creating a Custom `/products` Endpoint

So when someone does a Get, we can do some stuff.

Awesome. So I noticed you were trying to use the forward slash products thing, so why don't we try to insert that as a route.

Okay. So that'll become our new endpoint or endpoint route. If you've seen ASP.NET in the past, you may be familiar with routing. You should go and take a look in the Docs about the subtle differences between routing and endpoints. Endpoints is a little bit more flexible for what we're doing. We're going to say slash products, cool. Then this is a little tough, so you say comma, and then you can have this object, I call it context. You can call it whatever you want and then our rocket ship. Then we're going to go and open that up, and then close it, and close it. So let's just remind ourselves really briefly. That got opened there. See how Visual Studio is so smart.

Yeah, so nice.

It is nice. It got the close there. So our mustache is here, our curly braces there. So the rocket ship is going to point to the stuff that we're going to do.

Yeah.

So we can do a bunch of stuff. So the stuff goes here.

What we going to do.

Fetching and Serializing Product Data

All right. Now, this might look a little scary but you walked me through it before and I didn't feel too bad.

Okay. All right. So in this case, I think we just want to retrieve all the products again.

Right. Now because we're not in a page, we're going to have to go and get them manually, and this is actually no fun, and proves that the way we did it before was actually cool because services should be easy to get. So we have our app, an app's a thing, and we can ask all of our app's application services.

Go retrieve the specific service that we want.

Get me, which was called?

JSON File Product Service.

JSON File Product Service, cool. It's already getting too long and it's stressing me out.

Yeah.

Okay. Trust me, this will be worth it.

There's lots of function calls here too.

Teach a woman to fish. Now, GetProducts. Which was a function that exists in line that we made. All in one, like long breath line, you're going to go and say, app.ApplicationServices. Go and ask the app, "Give me this service, that GetProducts." So I could have just made one, but in this thing here, I'm actually saying, "You know about this, just give me that, it'll be easier. Life will be better if you go and make this happen for me."

Yeah.

All right. So then on the next line, we get the actual JSON.

So this case, we've got the JSON variable, and we need to serialize all those product objects.

Okay.

So we're going to use that JSON serializer again.

JSON serializer may not be available here, and I'm going to use that little light bulb, and get that using statement added at the top.

Really nifty.

Remember, all the way at the top it just added that JSONSerializer. Serialize. So not deserialize but serialize. We can make it a list of products, or whatever products. It's going to be in IEnumerable of product, another thing that we need to bring in from models. I'm just hitting "Control." to get that up very quickly. Then we're going to say, "These are the products. These ones here make me a string of those."

Yeah.

All right. Now, it is worth reminding ourselves and the audience, that we're doing this inside of startup.JSON, which is weird.

Yeah.

It is weird, but it's also showing you that there's a low-level, or like a down on the metal way that you can do things. In the next video, we're going to do this on a much better way I think. So far, we have retrieved our product by manually digging it out of the application services, pile of services, and then we serialized the product into some JSON. Let's go ahead and return that to the web browser, cool?

Good idea.

Returning the JSON Response

All right. So back to Visual Studio.

All right. So now let's go ahead and return. So we're going to use return keyword, and then context.response.

We have response and requests.

Yes.

So we're going to go back to response.

We're going to do write.

That's all right, I don't see write.

Yeah, that's interesting.

Let's go and do this.

Let's write it anyway and maybe we'll get the trustee.

Well, there we go.

Yeah.

So there's our WriteAsync is inside of.httpnamespace when I add that.

Light bulb to the rescue.

The light bulb is great. Look, and here we've got a different choices. We're going to return some text. So I'm just going to say JSON and add a semicolon, and that JSON, of course, it's this one right here.

Yeah.

All right. So then let's just go ahead and run this and see if it works. Sound like a plan?

Yeah.

Deal.

Fingers crossed.

It's low confidence.

You never know.

Testing the API and What's Next

No, it could work. So there's our web page, we knew that that worked. But remember, we made a slash products. There you go.

Nice. Normally, on my browser though, I don't see it that nicely formatted.

Yeah. Yeah. If you notice, I'm going to hit "Refresh", like watch again and really close.

Pause the frame.

It looks bad for a second.

Yeah.

Well, it turns out what I'm doing, I'm using the new Microsoft Edge, and it is based on chromium, and you can use JSONView. It's literally pretty JSON.

That's pretty.

All right. So I recommend that people try that out if you want to look at JavaScript. Because if you the reality, if I do a view source, we don't need to pause the frame.

Yeah.

That's the reality but of course, that's not for humans.

No. That's not for humans.

At least you can take it's most likely successful.

That's totally okay. That's not for humans. That's for the future mobile website or the mobile application that you mentioned.

Sure.

Cool. Now, again, not super fun.

No.

Let's take a break, come back, and make a real web API. That's much more friendly. Deal?

Deal.

Stick with us.