Introducing Endpoints
Published: 2019-12-04 19:56:21

Author: Alvaro Videla
Date: December 17, 2018
[Originally posted on the Fauna blog.] (https://fauna.com/blog/introducing-endpoints)

-----

When we introduced the [Fauna Shell](https://fauna.com/blog/introducing-fauna-shell), one of our goals was to make FaunaDB easier to use. In that article, we showed you how to get started with FaunaDB by using our [serverless cloud](https://fauna.com/faunadb/serverless-cloud) offering. Of course, we want to offer more, transforming it into the tool that makes your day-to-day usage of the database easier. In this blogpost, we show how to connect the shell to different FaunaDB instances. Enter endpoints.

#Endpoints#
To connect to different FaunaDB instances, we introduced the idea of endpoints into the Fauna Shell. We wanted them to be easy to manage—adding, listing, or removing endpoints had to be a frictionless task.

So, let’s say that you have two FaunaDB instances running: one in localhost used for development, and one instance in your private cloud. Let's create our first endpoint:

![Alt Text](https://thepracticaldev.s3.amazonaws.com/i/zs1jva1phyt5x0l6kood.gif)

```
$ fauna add-endpoint "https://localhost:443"
Endpoint Key: ****************************************
Endpoint Alias [localhost]: localhost
```
After running the <code>add-endpoint</code>, you will be prompted for both a database key for that endpoint and an endpoint alias. It should be something that lets you easily reference the endpoint, as we will see later (the default is the endpoint hostname). 

Now you can list endpoints and see that your endpoint was created successfully:

```
$ fauna list-endpoints
localhost *
```
Let's add a new endpoint:

![Alt Text](https://thepracticaldev.s3.amazonaws.com/i/kdg63ptifmlmxadml30x.gif)

```
$ fauna add-endpoint "https://cluster-us-east.example.com:443"
Endpoint Key: ****************************************
Endpoint Alias [cluster-us-east.example.com]: us-east
```

As you can see in this case, we changed the endpoint alias to have a shorter name, since we want to remember that this FaunaDB instance is running in our <code>us-east</code> cluster. Let's list endpoints again:

```
$ fauna list-endpoints
localhost *
us-east
```

There's our newly created endpoint <code>us-east</code>. You may have noticed that there's a star * next to the <code>localhost</code> endpoint name. That's a way to tell which one is the default endpoint used by the Fauna Shell when connecting to FaunaDB.

#Connecting to a different FaunaDB instance 
If you want the shell to connect to the <code>us-east</code> endpoint instead of using your <code>localhost</code> database, you can do that by setting <code>us-east</code> as the default endpoint by running this command:
![Alt Text](https://thepracticaldev.s3.amazonaws.com/i/x81ejcqwmsn7fgehzktd.gif)
```
$ fauna default-endpoint us-east
```
Let's list endpoints to make sure our change took effect:

```
$ fauna list-endpoints
localhost
us-east * 
```
#What about the Cloud endpoint?#
If you followed the steps in the Introducing [Fauna Shell](https://fauna.com/blog/introducing-fauna-shell) blog post, you may have ended up with a <code>cloud</code> endpoint as well:

```
$ fauna list-endpoints
cloud
localhost 
us-east *
```
That's because the <code>cloud-login</code> command showcased in the [previous blogpost](https://fauna.com/blog/introducing-fauna-shell) created a <code>cloud</code> endpoint for us.

#Deleting an endpoint#
Let's say that we decommission our <code>us-east</code> cluster and decide to run all our business out of Fauna Cloud. Then, we need to delete the <code>us-east</code> endpoint from our configuration.

First, we'll set the <code>cloud</code> endpoint as the default one:
![Alt Text](https://thepracticaldev.s3.amazonaws.com/i/4cblg61t1985saa12abq.gif)

```
$ fauna default-endpoint cloud
$ fauna delete-endpoint 'us-east'
```
Now, let's list endpoints again to see the results of running the previous commands:

```
$ fauna list-endpoints
cloud *
localhost
```
As you can see, Fauna Shell makes it easy to manage endpoints that connect to FaunaDB. Now, as a developer you might be wondering where is the endpoint configuration stored?

#What's happening behind the scenes?#
When we were designing the shell, we tried to keep the solution as simple as possible. That's why, when it came to storing this kind of configuration information, we decided to simply keep it inside an <code>ini</code> file in your home folder. Try checking the contents of the file <code>~/.fauna-shell</code>. (On Windows, that file will be in your home folder.)

Here's a sample <code>~/.fauna-shell</code>:

```
default=cloud

[localhost]
domain=localhost
port=8443
scheme=http
secret=the_secret

[cloud]
domain=db.fauna.com
scheme=https
secret=FAUNA_SECRET_KEY

[us-east]
domain=cluster-us-east.example.com
port=443
scheme=https
secret=OTHER_FAUNA_SECRET
```
By keeping things simple, we got a config file that fulfills its purpose while providing us with a very readable format (should our users try to connect to different endpoints).

#Conclusion#
In this blog post, we learned how to access different FaunaDB server instances from the Fauna Shell by declaring endpoints for each of them. This becomes quite useful when we want to run queries against different databases and servers. We can see that the shell comes packed with a handful of commands that will ease your day to day work with FaunaDB.