Hasura Hello World

This quickstart will take you over Hasura's instant backend APIs (BaaS) and how to deploy your custom code too.

Clone & deploy

Any project on hasura.io/hub can be cloned and deployed. In fact, this hello-world is a hasura project itself.

Step 1: Install the hasura CLI: installation instructions

Step 2: Create a hasura project on your machine

$ # 1) Run the quickstart command
$ hasura quickstart hasura/hello-world

Step 3: Deploy the project to your free cluster!

$ # 2) Git add, commit & push to deploy to your cluster
$ cd hello-world
$ git add . && git commit -m 'First commit'
$ git push hasura master

Note: Your free cluster got automatically created when you ran the quickstart command.

What got 'deployed'?

This hello-world project contains a sample data schema and some sample data (files in migrations). When you ran the git push these tables got created.

In the next few steps you'll be browsing the instant Hasura APIs and exploring adding custom microservice too.

Using the API console

The hasura CLI gives you a web UI to manage your data modelling, manage your app users and explore the Hasura APIs. The API explorer gives you a collection of all the Hasura APIs and lets you test them easily.

Access the api-console via the following command:

$ hasura api-console

This will open up Console UI on the browser. You can access it at http://localhost:9695

GraphQL / Data APIs

The Hasura Data API provides ready-to-use GraphQL APIs and also a HTTP/JSON API backed by a PostgreSQL database.

These APIs are designed to be used by any client capable of making HTTP requests, especially and are carefully optimized for performance.

The Data API provides the following features:

• GraphQL APIs with authorisation.
• CRUD APIs on PostgreSQL tables with a MongoDB-esque JSON query syntax.
• Rich query syntax that supports complex queries using relationships.
• Role based access control to handle permissions at a row and column level.

The url to be used to make these queries is always of the type: https://data.cluster-name.hasura-app.io/v1/query (in this case https://data.awesome45.hasura-app.io)

As mentioned earlier, this quickstart app comes with two pre-created tables author and article.

author

column	type
id	integer NOT NULL primary key
name	text NOT NULL

article

column	type
id	serial NOT NULL primary key
title	text NOT NULL
content	text NOT NULL
rating	numeric NOT NULL
author_id	integer NOT NULL foreign key

Alternatively, you can also view the schema for these tables on the api console by heading over to the tab named Data.

Let's look at a sample query to explore the Data APIs:

GraphQL Operations

GraphQL Operations are supported by Hasura Data APIs.

• Select all entries in the article table, ordered by desc rating:

query fetch_article {
  article (order_by: ["-rating"]) {
    id
    title
    content
    rating
    author_id
  }
}

For more examples of GraphQL queries, check out the docs

Auth APIs

Every app almost always requires some form of authentication. This is useful to identify a user and provide some sort of personalised experience to the user. Hasura provides various types of authentication (username/password, mobile/otp, email/password, Google, Facebook etc).

Signup

Lets look at an example for simple username/password signup.

• Signup using username and password: POST auth.cluster-name.hasura-app.io/v1/signup HTTP/1.1 Content-Type: application/json

{
  "provider" : "username",
  "data" : {
     "username": "johnsmith",
     "password": "somepass123"
  }
}

Typical response of a signup request looks like:

{
  "auth_token": "b4b345f980ai4acua671ac7r1c37f285f8f62e29f5090306",
  "username": "johnsmith",
  "hasura_id": 2,
  "hasura_roles": [
      "user"
  ]
}

Once a user is registerd (or signed-up) on Hasura, it attaches a Hasura Identity or (hasura_id) to every user. A Hasura identity is an integer. You can use this value in your application to tie your application’s user to this identity.

To learn more, check out our docs

Add instant authentication via Hasura’s web UI kit

Every project comes with an Authentication kit, you can restrict the access to your app to specific user roles. It comes with a UI for Signup and Login pages out of the box, which takes care of user registration and signing in.

Follow the Authorization docs to add Authentication kit to your app.

File APIs

Sometimes, you would want to upload some files to the cloud. This can range from a profile pic for your user or images for things listed on your app. You can securely add, remove, manage, update files such as pictures, videos, documents using the Hasura filestore.

This is done via simple POST, GET and DELETE requests on a single endpoint.

Just like the Data service, the File API supports Role based access control to the files, along with custom authorization hooks. (Check out our documentation for more!)

Uploading files

Uploading a file requires you to generate a file_id and make a post request with the content of the file in the request body and the correct mime type as the content-type header.

POST https://filestore.cluster-name.hasura-app.io/v1/file/05c40f1e-cdaf-4e29-8976-38c899 HTTP/1.1
Content-Type: image/png
Authorization: Bearer <token>

<content-of-file-as-body>

This is a very simple to use system, and lets you directly add an Upload button on your frontend, without spending time setting up the backend.

Downloading files

Downloading a file requires the unique file id that was used to upload it. This can be stored in the database and retrieved for download.

To download a particular file, what is required is a simple GET query.

GET https://filestore.cluster-name.hasura-app.io/v1/file/05c40f1e-cdaf-4e29-8976-38c899 HTTP/1.1
Authorization: Bearer <token>

Notify APIs

Check out the Learning center tab on the API Console for short tutorials on all the APIs!

Add your own custom microservice

Docker microservice

$ hasura microservice create <service-name> -i <docker-image> -p <port>

git push microservice

$ hasura microservice create <service-name>

Once you have added a new service, you need to add a route to access the service.

Let's say you want to add a microservice already present in another Hub project, you can make use of hasura clone. You can quickly add a Node.js microservice by running the following:

$ hasura microservice clone api --from hasura/hello-nodejs-express

This will clone the api microservice from hello-nodejs-express project available on Hub.

Add route for the service created.

$ hasura conf generate-route <service-name> >> conf/routes.yaml

It will generate the route configuration for the service and append it to conf/routes.yaml.

Add a remote for the service [Only for git push based services]

$ hasura conf generate-remote <service-name> >> conf/ci.yaml

This will append the remotes configuration to the conf/ci.yaml file under the {{ cluster.name }} key.

Apply your changes

$ git add .
$ git commit -m "Added a new service"
$ git push hasura master