Our First API Endpoint to Get Our Organization's Details

In This Lesson

We'll add the first endpoint to our API. With this endpoint we'll return back the Organization's details for the provided Access Token with the request.

Created by: @tomgobich
Published: 1 year ago

Join the Discussion 0 comments

Be the first to comment!

Transcript

So the first endpoint that we're going to be creating for our API inside of our application is for our organization. We're after the specific organization that the authentication token is for.
And if you'll recall back within our app middleware and our organization middleware, we are populating the organization onto our HTTP context
via that access token being used for the request already. So for this endpoint, we're not going to need to actually query our organization at all,
leaving us just needing the focus on getting our controller and our route created. So let's dig in first to our terminal to create that controller. So we'll do node ace make controller,
and we'll put all of our API based routes inside of an API controller directory. And we can call this our organization controller. We're only going to have one method within this controller.
So to simplify things for ourselves, we can call that method handle. Let's create that controller there and jump back into our text editor. Let's go into our controllers, API, organization controller.
And as we just saw, we're already populating the organization via the access token being used into our HTTP context. So we just need to grab that and return it back from our controller.
From there, since within our start routes, API route definition file, we're forcing the content negotiation for all of our API based requests to return JSON,
the organization that we're returning from our controller is going to be serialized and converted to JSON for the response. So how we have it is perfect. If you prefer to be a little bit more explicit, though,
you can reach for your response directly and then return response.json to specifically specify that this should return JSON from your controller.
Both how we have it here and how we had it before, thanks to that forced JSON response, will return the exact same. So let's leave it how we have it here, nice and simple for now.
Then we can dig into our API and on our route definitions, since we're getting our organization, we're going to want to define this as a router.get for its HTTP method.
And this is for our organization's resource. So we can do /organizations. However, this route is only ever going to return back one organization.
It will never return back a list because the organization being returned is bound to the authenticated token. And since it's bound to that token,
we don't necessarily need to know the ID because the token is providing that for us. So this is one of those instances where we're going to stray from the norm a little bit
to keep our API practical and just do /organization as that better defines exactly what we're after with this route definition. Then in terms of our controller,
we can have this target our organization controller. However, you're going to notice that we have three of these. So we have the main one here at controllers organizations.
Then we have the one for our settings panel at controllers settings organizations. And then finally, we have the one that we just created, controllers API organizations.
So make sure that you use the one within our API directory here for our API route definition. And now remember, you can always change the name of your imports if you want to be more explicit.
So you could always prefix all of these controllers with API if you wanted it to be very straightforward what organization controller it is that we're targeting.
I'm going to leave it nice and simple here so that we don't need to do that repeatedly for all of our controllers. But in a real application, we're going to be continuously working with the project. You may prefer to have that prefix.
Lastly, for all of our web based routes, we're giving our routes names. And that's done via this little as method chain to the end of our route definitions.
This is done to make referencing that route inside of our controllers and other code places easier so that we can easily point to this route from our code directly,
either for redirects or any other purpose. We're not going to need to do that for our API routes. We're never going to reference these routes anywhere within our controller. We're not going to need to do any redirects
or anything like that to any of these API routes. So we're going to omit those names from these route definitions altogether.
In addition to that, we also never want these route definitions to collide with our web route definitions. As you can see, we already have slash organization route definitions
defined within our web file here. We also have ones for slash difficulties, statuses, so on and so forth. And as we build out our API endpoints,
those will inevitably collide with one another in terms of our route definition names. So to prevent that, let's prefix all of our API-based routes
using the prefix method on our router group with slash API. That makes our organization route now slash API slash organization.
And that API prefix will ensure that this organization route never collides with our web route. Okay, cool. Now, in terms of our organization controller,
with APIs, it's generally good to provide more information than less so that we're trying to provide the application interfacing with our API,
all of the information that they may need for the resource that they're after. For our organization, that's most likely going to include our difficulty statuses and access levels
so that they don't need to do an individual request to get all of that for our organization. Now, that all does come down to a design decision on a per application basis.
If you have a ginormous application where your organization has an absolute boatload of things, you may choose to handle this different. For us, we only have these three resources.
So for our application, it's going to be more practical to just provide that to the user whenever they query for our organization. Our courses, however, have a lot more information tied to them.
So that is where it would be better to leave that as a separate endpoint. So let's go ahead and load in our difficulties and then we can reach through our organization and load in our statuses.
And then lastly, we'll await organization and load in our access levels. In case you're not familiar, we're using load off of our organization
rather than preload because the organization information itself is already queried for and populated onto our organization variable.
So we're not preloading it as the organization's already queried. So we're just going to lazily load it with the load method there. And that's going to populate those properties on our organization
so that now we'd be able to do something like organization.difficulties to loop over each of the difficulties within our organization.
And that too will get serialized and returned back with our organization response for this API.

Adding an API to an AdonisJS Web App

43 Lessons

5h 31m

Introduction

API Authentication

Getting Started with APIs

Organization Resources

Courses

Searching

Rate Limiting

Rate Limiting an Organization's HTTP Requests

13m 59s

Stop losing your best ideas!

Use our integrated note feature to capture and organize your key insights. Take a note at any timestamp and jump instantly back to that moment in the video with a single click.