Learn to Code via Tutorials on Repl.it!

← Back to all posts
Building a global app or API with a geo-distributed DB to serve requests closer to end users !
ChetanVenkatesh (0)

Getting Started With Global Apps & APIs

This tutorial should take about 15 minutes to complete.

Let’s create the backend for a simple Address Book app in the next few minutes. Our address book app will be run globally distributed with local read-write latencies on Macrometa’s global cloud platform.

Note: You need an account with Macrometa’s Cloud platform to build the backend for the app. If needed, you can get a free developer account at https://www.macrometa.co/start

Here's the Repl.it repo for this tutorial that shows you some of these steps in Python
Replit - Chetan's Python code for the address book

Building the geo-distributed backend engine for our app involves 3 steps:
1. Creating a geo-fabric to distribute our database and streams across worldwide locations we want to run our backend at
2. Creating a collection (like a table in SQL) and creating queries for CReate, Update and Delete (CRUD)
3. Exposing and consuming the CRUD queries as RESTful API endpoints

Step-1: Creating a geo fabric - a database that spans two or more global regions

Use your tenant credentials to login at https://try.macrometa.io

Once you login, you should see a dashboard with a map showing all the global locations provisioned for you to use.

The pin icons on the map represent all the locations to which the data will be automatically replicated, synchronized and stored in a deterministic manner. Applications can read and write locally from all these locations without waiting on synchronization for updates from other locations. By default, all data will be stored in all locations on your map. However, you can create specific geo-fabrics if you want to use a subset of the locations provided.

Step-2: Create an Address Book Collection

Collections in Macrometa’s are like tables in an RDBMS database. A collection contains zero or more documents. Macrometa is schema-less. You can read more about various data models supported by the database here.

Let’s start by clicking the COLLECTIONS menu entry, then the Add Collection tile. Give it a name, e.g. addresses, leave the other settings unchanged (we want it to be a document collection) and Save it.

A new tile labeled "addresses" should appear. You can click to open (it will be empty since we have not stored any data in it yet).

Note: The collection "addresses" will automatically be created in all locations where you see pin in the map.

Step-3: Generate CRUD REST API (RESTQL)

To store addresses in our address book app, we will use the following document format (or schema) for each contact:

"firstname": "John",
"lastname": "Doe",
"email": "[email protected]",
"zipcode": 56703

Click the QUERIES menu entry to open C8QL query editor. Then create the query shown in the screenshot below.

Let's execute the query to make sure it works correctly. Do this by clicking on the "Execute" button in blue.

Automatic REST API creation for queries
Let’s save the query with name addAddress. This query then automatically will be available as a REST end point for execution globally by its name addAddress. In short, within a second you have a globally distributed backend service for this functionality in your app. Simple right?

Let’s write queries for the other server-side capabilities we need in our AddressBook app. Save them with relevant names as follows:

Name: addAddress

INSERT { firstname: @firstname, 
        lastname: @lastname, 
        email: @email, 
        zipcode: @zipcode }
   INTO addresses

Name: getAddresses

FOR address IN addresses
    RETURN address

Name: updateEmail

UPDATE { _key: @key }
  WITH { email: @email }
  IN addresses

Name: removeAddress

REMOVE { _key: @key} 
  IN addresses

You can read more about how to write C8QL queries here.


Click the SUPPORT menu entry and open the API Browser. Scroll down and to see RESTQL api.

You can execute RESTQL API from anywhere in the world. The Macrometa fast data platform will take care of intelligently routing the request to the location closest to your app, and return results from that location.

To see Macrometa in action, let’s execute our getAddresses API using the curl command. Click on SUPPORT, scroll down to RESTQL, and select the POST option to "Execute restql by name". After adding your tenant name, fabric name, and query name (in this case, getAddresses), select Execute and you'll see the Curl syntax is built for you.

In the screenshot above, Macrometa’s platform routed the request and executed in Los Angeles, US datacenter as that is closest to my current location (Macrometa is based in Palo Alto).

theangryepicbanana (1635)

It would be nice if this was actually done on repl.it

ChetanVenkatesh (0)

@theangryepicbanana My sincere apologies - I'm right in the middle of figuring out how to. Will re-edit and post once I figure this out.

theangryepicbanana (1635)

@ChetanVenkatesh no need to apologize. I just thought it would be a good idea since you posted the tutorial on repl.it

ChetanVenkatesh (0)

@theangryepicbanana Hi - Ive created a python tutorial for this - https://repl.it/@ChetanVenkatesh/Programming-Macrometa-Global-geo-distributed-DB-in-Python

Question - how do I edit this tutorial to add this to it? Any ideas? First time on Repl.it here

Many thanks!

theangryepicbanana (1635)

@ChetanVenkatesh there should be an edit button under the text of your post

ChetanVenkatesh (0)

@theangryepicbanana found it ! doh! it was right there and I didnt see it :)

thanks for the help!

theangryepicbanana (1635)

@ChetanVenkatesh lol no problem (btw could you make a ruby or js tutorial too? not everyone uses python)

ChetanVenkatesh (0)

@theangryepicbanana yes! JavaScript for sure - I'll do that next. This is so awesome - i havent had this much fun in about 15 years (since I got into management)