Blog

- August 10, 2015

In a recent article about our Web app and API for displaying fireworks around your area, we ended up with URLs like https://fireworks.apispark.net/v1/html/index.html. These URLs are specific to the APISpark platform, and you may want to have a more personalized URL to share! This is where APISpark custom domains come in handy!

In this article, we’ll take this fireworks API, follow the steps described in our custom domain section of our user guide, and we’ll setup a nice URL for our API. In my case, I had a webapi.club domain name I wasn’t using, so I’ll be using it for this example.

First of all, click on account name in the top right hand corner of the APISpark console, and select “My account”.

custom-domain-01

Then click on “My domains”, where you’ll be able to setup your custom domain name to be used by your APIs, by clicking the “Add” button in the left panel:

custom-domain-02

Once you’ve clicked the “Add” button, the following dialog box will open:

custom-domain-03

You should select “Custom”, as you want a custom domain name, not a sub-domain of apispark.net (but you might have an API with different apispark.net subdomains if you need that). You type the name of your domain name (in my case “fw.webapi.club”). You select “DNS aliasing”. The other option is “DNS delegation” and uses another approach that is not fully automatic and requires our support to take care of it, but don’t hesitate to ask us if that’s your favored approach.

Once you’ve filled the form of that dialog box, you should arrive to the following screen, giving you some details about how to configure the domain name on the registrar side, and that will allow you to add a new binding between that domain name and the API we want to use it for.

custom-domain-04

In my case, I used Gandi for my domain name. This step is very different from one registrar to the other, so it’s not worth showing a screenshot, but the configuration should ultimately look like the one defined in the above screenshot. In my case, I have a

fw 10800 IN CNAME apispark.net.

Next, it’s time to add the binding between the domain name and the endpoint in your API, as hinted earlier. When clicking on the “Add binding” link, you will see the following dialog.

custom-domain-06

I choose ‘/’ as the base path where my custom domain will actually point at. So the paths relative to my custom domain will be /towns to get the list of towns and their fireworks, and /html/index.html for the web pages (as explained in our previous article, a mix of a Google Sheets document and a Github file store for the web assets.)

For the “API”, I chose “fireworks”, which is the API cell in APISpark for which I want to use a custom domain. And finally, I chose “/v1” to say I want to use my domain name for my v1 versions of the API (you could very well have a test.foo.com and stable.foo.com for different versions of your API.) By chosing v1, the v1 part in the path won’t be needed in my URLs, thus making my URLs slightly shorter in the process.

One last step, as the information tells us, we must go to our API and click the “Deploy” button to make this new custom domain live for our API. And now your custom domain is serving your web assets and API!

Now, you can access my little fireworks listing with http://fw.webapi.club/html/index.html.