The “no api” api for Next.js apps.

You started with that project of yours. You know, the one you have been putting off for so long. You want to build some nice proof-of-concept app using Next.js framework, but as for any application you will need an API. Maybe you want your users to login to your app, or you just want to preserve some data to be displayed in your shiny new app.

So now, instead of focusing on your groundbreaking new app that is going to make you a lot of money, you need to start by writing a boring API. You know, the API you already wrote many times before. You can use API routes in your framework and not worry about routing, but you still need to handle database connection, authentication token generation, cookies, user sessions and all the other stuff. Maybe you will copy it from the previous side-project.

But what if I told you, you don’t need to write the same API again and again? Because I did it for you already 😎 Ok, I did it for me, but thanks to the wonders of open-source software you can use my work for your own project too 👍

More IPA, less API🍻

Introducing @mathio28/next-api

I really wanted to go with just “next-api”. But guess what, picking out a name for your NPM package is the hardest part of writing and publishing a library. Most names will be already taken. I also wanted to use “@mathio/next-api”, but guess what… taken! So I guess all my future packages are stuck with “@mathio28/” prefix now.

You can find the open-source library @mathio28/next-api on Github:
https://github.com/mathio/next-api

So what is this? It is an API so you don’t need to write an API. It is a one-API-fits-all™ solution. You can start by installing it just like any NPM package:

yarn add @mathio28/embed

This will create /pages/api/[collection].js API route to handle all API calls. All you need to do now is specify MONGODB_URL env variable.

Photo by Olesya Grichina on Unsplash

Using the API

📚 CRUD endpoints

Now you can GET, POST, PUT or DELETE any endpoint to interact with your API. Do you want to create a new blog post? Just POST any object to /api/post. You can retrieve all blog posts via GET to /api/post. PUT will update existing blog posts and DELETE will permanently remove them.

Since the API is using MongoDB NoSQL database, the endpoints will save any object you throw at them. It will also return the same object you saved with some additional fields, eg. “created” with the timestamp of when the object was created.

📄 Singleton endpoints

For each collection you can create as many objects as you want. The only exceptions are collections starting with “one-” prefix, eg /api/one-config. You can make a GET request to retrieve the object or PUT to update it (no need to specify any IDs, since there is only one object). You can not DELETE it or use POST to create a new one.

🔐 Built-in authentication

For user authentication you can use special /api/auth endpoint:

• POST /api/auth create new user (email and pwd required) or update current user if authorized already
• PUT /api/auth login with email and pwd in body (generate token and set cookie)
• GET /api/auth get currently logged user (based on cookie)
• DELETE /api/auth logout (delete token and cookie)

The authentication cookie is set as HTTP for path /api. Your frontend app will not have access to the cookie (security 🚀) and you don’t have to think about it at all — it works out of the box 📦

️️️⚙️ Configuration

By default you don’t need to configure the library. But there are a few options you can change if you want:

import nextApi from ‘@mathio28/next-api’
import { SECURITY } from ‘next-api/config’
export default nextApi({
 // default security settings for database
 security: SECURITY.USER_SANDBOX,
})

The most relevant setting you might want to change based on your app is security. Available settings are (integer):

• SECURITY.NONE (0) — no security, anyone can get, edit and delete all collections
• SECURITY.USER_SANDBOX (1) — user can get, edit and delete only the collections they created
• SECURITY.READ_ALL (2) — user can get all collections, but can edit and delete only collections they created

🤓 Advanced usage

There are a few more configuration options available for advanced usage.

You can also override the security setting for each document by setting acl_read and acl_write variables (each one is an array of user IDs allowed to read or write the document).

You can also execute side effects — custom code before or after the route code is executed. An example use case is to validate data or transform data before they are returned to the client.

Full documentation can be found in the README file on Github:
https://github.com/mathio/next-api#readme

Next steps

The idea behind this library is to be reusable for most apps you might want to build. It is not intended for production usage, but I guess it could work just fine. I am open to suggestions for any new features if you are missing anything. However you can achieve most customizations via custom side effect callbacks (see advanced usage above) so give that a try first. I would be happy to help you with your use case.

In the future I would like to rewrite it in Typescript so any help towards this is more than welcome.

If you find my @mathio28/next-api library helpful please star it on Github or let me know on Twitter @mathio28.