Code Monkey home page Code Monkey logo

android-sdk's Introduction

Android SDK

The Android SDK for Hasura.

NOTE

This sdk works with Hasura running on version below 0.15.

Installation

Step 1 : Download the Hasura Android SDK

Using Gradle:

Add this to your project level build.gradle file

allprojects {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

Next, Add the following to your app level build.gradle

dependencies {
   compile 'com.github.hasura.android-sdk:sdk:v0.0.9'
}

Using Maven:

Add the JitPack repository to your build file

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

Add the dependency

<dependency>
  <groupId>com.github.hasura.android-sdk</groupId>
  <artifactId>sdk</artifactId>
  <version>v0.0.9/version>
</dependency>

Step 2 : Setup Hasura

Project Config

You set the project name and other hasura-project related things in Project Config object.

//Minimum Config
ProjectConfig config = new ProjectConfig.Builder()
                 .setProjectName("projectName") // or it can be .setCustomBaseDomain("myCustomDomain.com")
                 .build()

Other methods available are :

  • .enableOverHttp() // if included, then every network call is made over http (https is default)
  • .setDefaultRole("customDefaultRole") // if not included then "user" role is used by default
  • .setApiVersion(2) //if not included v1 is used by default

Use the above project config to initialise Hasura.

Hasura.setProjectConfig(config)
  .enableLogs() // not included by default
  .initialise(this);

Note: Initialisation MUST be done before you use the SDK.The best place to initialise Hasura would be in your application class or in your Launcher Activity.

Hasura Client

The HasuraClient object is the most functional feature of the SDK. It is built using the project config specified on initialisation. You can get an instance of the client only from Hasura, like so :

HasuraClient client = Hasura.getClient();

Hasura User

HasuraClient provides a HasuraUser object for all of your authentication needs(login, signup etc). This ensures that certain data can only be accessed by authorized users.

You can get an instance of the HasuraUser from the HasuraClient like so :

HasuraUser user = client.getUser();

SignUp

user.setUsername("username");
user.setPassword("password");
user.signUp(new SignUpResponseListener() {
            @Override
            public void onSuccessAwaitingVerification(HasuraUser user) {
              //The user is registered on Hasura, but either his mobile or email needs to be verified.
            }

            @Override
            public void onSuccess(HasuraUser user) {
              //Now Hasura.getClient().getCurrentUser() will have this user
            }

            @Override
            public void onFailure(HasuraException e) {
                //Handle Error
            }
        });

Note: All network calls are called on a non ui thread and all the callbacks are pushed into the ui thread.

Login

user.setUsername("username");
user.setPassword("password");
user.login(new AuthResponseListener() {

            @Override
            public void onSuccess(HasuraUser user) {
              //Now Hasura.getClient().getCurrentUser() will have this user
            }

            @Override
            public void onFailure(HasuraException e) {
                //Handle Error
            }
        });

LoggedIn User

Each time a HasuraUser is signed up or logged in, the session is cached by the HasuraClient. Hence, you do not need to log the user in each time your app starts.

HasuraUser user = client.getUser();
if (user.isLoggedIn()) {
  //This user is logged in
} else {
  //This user is not logged in
}

Log Out

To log the user out, simple call .logout method on the user object.

user.logout(new LogoutResponseListener() {
            @Override
            public void onSuccess(String message) {

            }

            @Override
            public void onFailure(HasuraException e) {

            }
        });

Data Service

Hasura provides out of the box data apis on the Tables and views you make in your project. To learn more about how they work, check out the docs here

client.useDataService()
  .setRequestBody(JsonObject)
  .expectResponseType(MyResponse.class)
  .enqueue(new Callback<MyResponse>, HasuraException>() {
                    @Override
                    public void onSuccess(MyResponse response) {
                      //Handle response
                    }

                    @Override
                    public void onFailure(HasuraException e) {
                        //Handle error
                    }
                });

In the above method, there are a few things to be noted :

  • .setRequestBody(): This is an overloaded method which accepts either an object of type JsonObject or a POJO (ensure that the JSON representation of this object is correct)
  • .expectResponseType(): Specify the POJO representation of the expected response.

Note: In case you are expecting an array response, use .expectResponseTypeArrayOf(). All SELECT queries to the data service will return an array response.

If the HasuraUser in the HasuraClient is loggedin/signedup then every call made by the HasuraClient will be
authenticated by default with "user" as the default role (This default role can be changed when building the project config)

In case you want to make the above call for an anonymous user

client.asAnonymousRole()
  .useDataService()
  .setRequestBody(JsonObject)
  .expectResponseType(MyResponse.class)
  .enqueue(new Callback<MyResponse>, HasuraException>() {
                    @Override
                    public void onSuccess(MyResponse response) {
                      //Handle response
                    }

                    @Override
                    public void onFailure(HasuraException e) {
                        //Handle error
                    }
                });

In case you want to make the above call for a custom user

client.asRole("customRole") //throws an error if the current user does not have this role
  .useDataService()
  .setRequestBody(JsonObject)
  .expectResponseType(MyResponse.class)
  .enqueue(new Callback<MyResponse>, HasuraException>() {
                    @Override
                    public void onSuccess(MyResponse response) {
                      //Handle response
                    }

                    @Override
                    public void onFailure(HasuraException e) {
                        //Handle error
                    }
                });

Note: This role will be sent JUST for this query and will not become the default role.

Query Template Service

The syntax for the query template service remains the same as Data Service except for setting the name of the query template being used.

client.useQueryTemplateService("templateName")
  .setRequestBody(JsonObject)
  .expectResponseType(MyResponse.class)
  .enqueue(new Callback<MyResponse>, HasuraException>() {
                    @Override
                    public void onSuccess(MyResponse response) {
                      //Handle response
                    }

                    @Override
                    public void onFailure(HasuraException e) {
                        //Handle error
                    }
                });

Filestore Service

Hasura provides a filestore service, which can be used to upload and download files. To use the Filestore service properly, kindly take a look at the docs here.

Upload File

The upload file method accepts the following:

  • either a File object or a byte array (byte[]) which is to be uploaded.
  • a mimetype of the file.
  • FileUploadResponseListener which is an interface that handles the response.
  • FileId (optional): Every uploaded file has an unique Id associated with it. You can optionally specify this fileId on the uploadFile method. In case it is not, the SDK automatically assigns a unique Id for the file.
client.useFileStoreService()
                .uploadFile(/*File or byte[]*/, /*mimeType*/, new FileUploadResponseListener() {
                    @Override
                    public void onUploadComplete(FileUploadResponse response) {
                      //Success
                    }

                    @Override
                    public void onUploadFailed(HasuraException e) {
                      //handle error
                    }
                });

FileUploadResponse object in the above response contains the following:

  • file_id: The uniqiue Id of the file that was uploaded.
  • user_id: The id of the user who uploaded the file.
  • created_at : The time string for when this file was uploaded/created.

Download File

client.useFileStoreService()
         .downloadFile("fileId", new FileDownloadResponseListener() {
                    @Override
                    public void onDownloadComplete(byte[] data) {
                      //successfule
                    }

                    @Override
                    public void onDownloadFailed(HasuraException e) {
                      //handle error
                    }

                    @Override
                    public void onDownloading(float completedPercentage) {
                      //download percentage
                    }
                });

Custom Service

In addition to the Data, Auth and FileStore services, you can also deploy your own custom service on Hasura. For such cases, you can still utilize the session management of the SDK to make your APIs. Currently, we have support for Retrofit.

Using a custom service - Retrofit Support

  • Let's say you have a custom service set up on Hasura called "api"
  • Your external endpoint for this custom service would be -> "api..hasura-app.io"
  • This is a wrapper over Retrofit for custom services, assuming that your interface with the api definitions is called "MyCustomInterface.java"

Step1: Including the retrofit support

Using Gradle:

Add the following to your app level build.gradle

dependencies {
   compile 'com.github.hasura:android-sdk:custom-service-retrofit:v0.0.999999999'
}

Using Maven:

Add the dependency

<dependency>
  <groupId>com.github.hasura.android-sdk</groupId>
  <artifactId>custom-service-retrofit</artifactId>
  <version>v0.0.9/version>
</dependency>
Step2: Build your custom service (before Hasura Init)
RetrofitCustomService<MyCustomInterface> cs = new RetrofitCustomService.Builder()
                .serviceName("api")
                .build(MyCustomInterface.class);
Step3: Add this custom service during init
Hasura.setProjectConfig(new HasuraConfig.Builder()
                 .setProjectName("projectName") // or it can be .setCustomBaseDomain("somthing.com")
                 .enableOverHttp() // if not included, then https by default
                 .setDefaultRole("customDefaultRole") // if not included then "user" role is used by default
                 .setApiVersion(2) //if not included v1 is used by default
                 .build())
  .enableLogs() // not included by default
  .addCustomService(cs)
  .initialise(this);
Step4: Accessing Custom Service
MyCustomService cs = client.useCustomService(MyCustomInterface.class);
Bonus: Handle the Response

RetrofitCallbackHandler is a helper class which you can use to handle the responses from your custom APIs and parse errors.

EXAMPLES

Check our this for sample apps built using the SDK.

ISSUES

In case of bugs, please raise an issue here

android-sdk's People

Contributors

jaisontj avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

android-sdk's Issues

Error to Run

I have problems to Run the example of the project.

Cheers. #hacktoberfest

Readme: Webhooks

There should be some instructions in the readme regarding the permission webhook that one needs to create in order to use the Filestore service.

Readme Errors

  1. Hasura Initialization:
    Note specific to use cases of extra options to be added. Else people will blindly copy config for all different options availabe. eg using enableOverHttp() option would give 405 error for Auth/Data Services.

  2. FileStore upload:
    Note specifying the second argument of file upload (/ *File * /) can be both File object as well as byte[ ].
    Also note specifying providing filename is not essential

Login using OTP

end-point : otp-login has an error
Gives a 401 unauthorized for a login request, onFailure() method gets called, yet otp is sent

Libraries used

Mention the libraries that are used for the sdk. For eg, GSON is used for JSON parsing, OkHttp for networking etc.

Social login integration Google+

It is given in hasura docs that once an id_token is received from Google it has to be sent to hasura. Exactly how to do that is nowhere mentioned in the README.md

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.