Beautifying your API URL with Netlify

When it comes to URLs, it's best to look good

From the post about deploying APIs on Netlify, one thing probably stands out–the default URL structure to the Lambda functions is a bit ugly. Given the great lengths API developers and architects go through to make pretty URLs, this could be a show-stopper for many teams who want beautiful URLs.

That is, this URL:

https://fehguy.eatbacon.org/.netlify/functions/api/swagger.json

Is certainly functional, but what if we want to have a major version number in it, for compatibility? Most developers look for this information just after the host, like such:

https://fehguy.eatbacon.org/v1/swagger.json

Luckily there’s a simple solution built into the Netlify CDN. Using a somewhat misleading concept–redirects, you can provide routing information to the Netlify edge CDN so you can hide the .netlify/functions/api path. This is accomplished with one of a couple methods:

1. A _redirects file at the root of the public portion of the webapp
2. A redirects section in the netlify.toml configuration file

Both are simple, so let’s go with the _redirects file approach. First, create the file, and add a single line like this:

/v1/*      /.netlify/functions/api/:splat  200

This means, route all requests starting with /v1/ to the /.netlify/functions/api/ path, and append any path parameters after the /v1/ in place of the :splat placeholder.

Note, the 200 in this file is also a bit misleading, because this will not set the HTTP response code for these proxied calls! It simply indicates that the Netlify proxy should not send a 302 redirect when the URL is hit.

Query Parameters

There is one catch, though, and this probably will go away at some point. Query parameters in the _redirects file must be explicitly declared and matched per route. That means this:

/v1/users?limit=10

Must be matched by a _redirects file entry like this:

/v1/users limit=:limit /.netlify/functions/api/users?limit=:limit 200

Eeeks, this is a lot of work to maintain. In a later post, we’ll put together an auto-generated _redirects file script to get around this error-prone and tedious step.

Build Process

Now, ensure this file is copied during your build process. If you’re using gulp like many of the netlify-cms templates do, you can add a simple task:

gulp.task('copy', function () {
    gulp.src('_redirects')
        .pipe(gulp.dest('./dist/'));
});

and enable it in the appropriate stage. For my project, it’s the build stage of a hugo project:

gulp.task("build", ["css", "js", "cms-assets", "hugo", "copy"]);

Now during the build, the _redirects file is copied from the root of the project to the dist folder, and is ready to be used by the proxy for configuration.

That’s it! Now the real path to the Lambda functions is masked behind our vanity URL, and we can stop being embarrassed of our old, ugly URL.

It’s worth pointing out some amazing potential with this proxy. How about when you version your API? It is now trivial to map between completely different versions of lambda functions, which means you can provide a better user experience during a version transition. This also means you should probably start thinking about your API versioning strategy, but we’ll save that discussion for a later post.