Build REST APIs with Deno and Oak

Deno is a new Javascript runtime, created by Ryan Dahl. Version 1.0 released on 13th May 2020. The most notable Deno features are security and URL importing. By default Deno blocks access to any system resources, unless it’s explicitly asked. Deno also doesn’t have any package manager, all libraries are loaded from CDN. All these unique features of Deno, make me curious. Hence, I decided to get my hands dirty with Deno. I’ve prepared a very simple RESTful application. In this article, you will learn how to build REST APIs with Deno and Oak middleware.

The famous User application

Since I don’t want to overwhelm you with complex business logic, I stick to the famous User API that I covered numerous times on this website. Essentially, we are going to build a simple CRUD RESTful User app that has no persistence, means for now we store all data in an array for simplicity’s sake.

We are going to create the following APIs:

GET / – displays welcome page
GET /v1/users – returns a list of users
GET /v1/users/:id – gets a user by id
POST /v1/users – creates a new user
PUT /v1/users/:id – update an existing user
DELETE /v1/users/:id – deletes a user by id

As you can see, the APIs are very rudimentary and the only remaining challenge is how to implement the project itself.

Project scaffolding

Remember we don’t NPM or any package manager, so we can’t rely on them to scaffold our project. All we have to do is to create a simple .js file and start coding right away.

Some may say,

But wait what about dependencies? Don’t we suppose to download them?

The answer is:

Yes and no!

We just need to add their CDN URLs using the import statement and then Deno takes care of the rest. Sounds confusing? Don’t worry. It will become crystal clear once we start coding.

Implementing the APIs

Deno has a built-in HTTP server but doesn’t have all features to build RESTful APIs. To make our task easier, we use Oak library. Oak is a middleware framework for Deno’s HTTP server, including a router middleware. You can see it as Express in Node.js world 🙂

Root endpoint implementation

First, let’s create the index.js file and write the following couple of lines of code.

The first line imports the Application and Router from Oak. As you can see they are loaded from CDN. The dependencies will be downloaded (first time) automatically if they don’t already exist on your computer.

In the second line we create an instance of the router. Then we add the / resources that greet users with a welcome message.

The input of the method is the context object. This object contains all we need for this project implementation such as request, request.body, request.params, etc. I highly recommend you to check the Oak documentation.

The rest starts an HTTP server and listens to port 8080.

Now let’s start to run the project. Open your terminal and type,

Wait what!!?? You got this error message:

Remember at the beginning of the article I mentioned Deno is secured and any permission should be asked explicitly. This is an example of it. We have to ask explicitly to get access to the network. Hence, we need to run this command.

`GET /v1/users` implementation

Since the project foundation is ready, implementing the rest of the code is very easy.

Let’s create a dummy array to act as temporary storage and hold users.

Then, we need to have another get implemented like this,

Now if you hit localhost:8080/v1/users, you should get a list of users stored in dummyUsers constant.

`GET /v1/users/:id` implementation

For this endpoint, all we have to do is to filter the dummyUsers by id and return the user if it exists. Otherwise, throw 404.

For that we create a function called getById.

And then implement the endpoint,

The code has some additional checking to ensure the passed parameter exists and it’s a number. The rest is the same as explained before.

`POST /v1/users/` implementation

We expect the API consumer to pass a user and it should be added to the dummyUsers array. We don’t have any checks for duplication. The only restriction is age that must be a number and the rest of the fields (firstName, lastName) should be present.

To check and get the request body we can rely on context.request.hasBody and context.request.body functions. The latter returns a promise which means the endpoint should be async.

The first block does some validations to ensure the body exists. Then the value of the body is read and finally after verification a new record is added to the dummyUsers array. Otherwise, it returns 400.

`PUT /v1/users/:id` implementation

Similar to the POST endpoint we need to read request.body which makes the implementation quite similar to the previous section,

To update an element in the array the code utilizes the splice function.

`DELETE /v1/users/:id` implementation

This is the last endpoint. We can copy GET /v1/users/:id and do some slight modifications as follows,

That’s all you need to build Rest APIs with Deno and Oak 😀

You can find the complete workable example on my GitHub at the link below,
https://github.com/kasramp/deno-oak-rest

The entire project is a single file. Isn’t it fantastic? No package.json, and package-lock.json are required. We can take the Deno executable (again it’s a single file) and the project file and run it anywhere without problems.

All it takes to run the project are two files (Deno executable, and the project implementation). This gives a huge advantage if we need to run the project in the container or deploy it to a cloud environment.

If you enjoyed this article, don’t forget to check my previous Deno related article “Is Node.js dying?“.