Skip to main content

Overview

This JavaScript Client API documentation will guide you how to use the key modules of the client library to integrate your Agnost backend apps with your frontends.

Key modules​

There are several modules in our client library that you can use in your frontend applications.

  • Authentication - Handles the authentication process of your application users. Provides methods to manage users, sessions and authentication. You are free to design the way to authenticate your users and manage sessions in Agnost through defining your custom data model and endpoints. However, by default Agnost provides email, phone number and 3rd party oAuth provider based authentication to manage user accounts through the client library.
  • Cloud Storage - Provides the methods to manage your app's cloud storage files. With this module you store your files, documents, images etc. under buckets, which are the basic containers that hold your application data.
  • Endpoints - Provides the methods to execute your app backend services by making REST API requests to your app endpoints. You can use any HTTP client to call your app endpoints, however, the client library provides conveniece methos to make GET, POST, PUT and DELETE method calls to your endpoints.
  • Realtime - Allows realtime publish and subscribe (pub/sub) messaging through websockets. Realtime makes it possible to open a two-way interactive communication session between the user's device (e.g., browser, smartphone) and a server. With realtime, you can send messages to a server and receive event-driven responses without having to poll the server for a reply.

Response structure​

Ignoring few exceptions (e.g., auth.getSession, auth.getUser), the client library method executions return a json object which includes two main components, the method response data and the errors.

Success response​

If the client library method exeuction completes successfully then the returned json object's response data field(s) will be populated and the errors field will be set to null. The response data structure can be different for each method. Please refer to the specific method's documentation for the response data structure.

//Get user and session data using the accessToken
const result = await agnost.auth.getAuthGrant(accessToken);
Success response example
{
  "user": {
    "_id": "6235e0eb25de47092f4d5300",
    "provider": "agnost",
    "providerUserId": "6235e0eb25de47092f4d5300",
    "email": "[email protected]",
    "signUpAt": "2022-03-19T13:55:55.772Z",
    "lastLoginAt": "2022-03-19T13:58:42.376Z",
    "emailVerified": true,
    "name": "Rooby"
  },
  "session": {
    "userId": "6235e0eb25de47092f4d5300",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbnZJZCI6I...",
    "userAgent": {
      "ua": "",
      "browser": {
          "name": "",
          "version": "",
          "major": "" 
      },
      "engine": {
          "name": "",
          "version": ""
      },
      "os": {
          "name": "",
          "version": ""
      },
      "device": {
          "model": "",
          "type": "",
          "vendor": ""
      },
      "cpu": {
          "architecture": ""
      }
  },
    "creationDtm": "2023-10-24T08:04:23.013+00:00"
  },
  "errors": null
}

Error response​

If the client library method exeuction has errors then the returned json object's response data will be null and the errors field will include the list of errors occurred.

// Sign in using email and password
let result = await agnost.auth.signInWithEmail("[email protected]", "password");
Error response example
{
  "data": null,
  "errors": {
    "status": 400,
    "statusText": "Bad Request",
    "items": [
      {
        "origin": "client_error",
        "code": "invalid_credentials",
        "message": "Invalid credentials. Email or password provided is invalid."
      }
    ]
  }
}
note

You can check the returned json object's errors field value to identify failures. If the value of errors is null, this means that the method call completed successfully otherwise errors field will hold the list of errors occured.