RoSaaS API Integration

Welcome to the Integration Guide for connecting your External System with the RoSaaS platform. This guide will walk you through the necessary steps to integrate your product's external system with RoSaaS, enabling seamless communication and interaction between your system and RoSaaS features.

Introduction

This documentation outlines the integration process for external systems to seamlessly interact with RoSaaS system. To establish integration, external systems are required to implement a specific set of designated endpoints. The RoSaaS system will invoke these endpoints in response to specific events. Additionally, external systems can also consume the existing endpoints provided by the RoSaaS system, thereby enabling them to leverage the capabilities and features RoSaaS system offer. Adherence to the outlined guidelines is crucial to ensuring smooth communication and achieving effective integration.

External Systems Implementing Endpoints

Overview

In this section, external systems are required to implement designated endpoints to facilitate seamless communication between our systems. These endpoints will be invoked by RoSaaS system in response to specific events, enabling the exchange of information.

Integration Guidelines

External systems should implement these endpoints within the tenancy management service as custom HTTP requests (Webhooks), defined by you as the product’s owner. These endpoints are triggered by events that occur on a product’s tenant, such as tenant creation, activation, or deactivation. When such events occur, the RoSaaS system sends an HTTP request to the URI specified in the RoSaaS Control Panel. This mechanism ensures timely and accurate data exchange between RoSaaS system and external systems.

  1. Creation - POST Method:
    Upon tenant creation, the RoSaaS system automatically sends an HTTP request to the external system along with the new tenant’s uninqu name. This request prompts the external system to construct and activate the required tenant resources.
  2. Activation - POST Method:
    When RoSaaS’s admin updates the status of a tenant to “activating”, the RoSaaS system automatically sends an HTTP request to the external system along with the tenant’s uninqu name. The external system then proceeds to activate the tenant’s resources.
  3. Deactivation - POST Method:
    When RoSaaS’s admin updates the status of a tenant to “deactivating”, the RoSaaS system automatically sends an HTTP request to the external system along with the tenant’s uninqu name. The external system then proceeds to deactivate the tenant’s resources.
  4. Deletion - POST Method:
    When RoSaaS’s admin updates the status of a tenant to “deleting”, the RoSaaS system automatically sends an HTTP request to the external system along with the tenant’s uninqu name. The external system then proceeds to delete the tenant’s resources.
  5. Unavailable (Tenant is Down) - POST Method:
    The RoSaaS system automatically and periodically checks the availability (health status) of tenants. When the RoSaaS system detects that a tenant is unavailable, it sends an HTTP request to the external system along with the tenant’s uninqu name to inform it that the tenant is down/unavailable.
  6. Health Check - GET Method:
    The RoSaaS system automatically and periodically checks the availability (health status) of tenants. The RoSaaS System checks the health status of a product’s tenants by sending an HTTP request to a default Health Check URL for the product’s tenants.

Implementation Guidelines

1. HTTP Response Consistency

All implemented endpoints must consistently return an HTTP status code of 200 upon successful request execution. This status code indicates that the request was successfully processed by our system.

2. Security and Authentication

For enhanced security, all endpoints must be protected using an API key. External systems must include this API key in the Authorization header of every request. Failing to provide a valid API key will result in a 401 response, indicating unauthorized access.

3. Endpoint Type and Request Format

Each POST request must include a JSON request body with the following structure:

{
  "tenantName": "string"
}

The tenantName parameter represents the unique identifier of the tenant associated with the specific event.

Example Request 

POST /api/integration/event-endpoint HTTP/1.1
Host: your-system.com
Content-Type: application/json
api-key:{your-api-key}
{
  "tenantName": "example-tenant"
}

4. Health Check

When implementing this endpoint, please consider the following instructions:

  • All the previous instructions must be adhered to when implementing this endpoint.
  • The GET request must Include a parameter in the route named “name” with the following structure:
{Host}/api/integration/{name}/health-status

The tenant-5 is unique name of the tenant that represents the name parameter.

Example Request 

GET /api/integration/tenant-5/health-status HTTP/1.1
Host: {your-system.com}
api-key:{your-api-key}

Consuming Existing Endpoints

Introduction

In this section, external systems can cunsume ROSAS system’s existing endpoints to benefit from its capabilities and features. These endpoints offer a user-friendly way to interact with core system functionalities and are designed with robust error handling and a consistent response structure.

ROSAS API Overview

ROSAS API offers a user-friendly approach for engaging with the core features of our system. All endpoints are meticulously crafted with robust error handling and adhere to a consistent response structure. This ensures a unified and informative experience for users, resulting in smooth interactions and clear, easily responses.

Authentication and Access

All endpoints are secure and require proper authentication. You’ll need to include an access token in your request header. If your authentication is missing or incorrect, you’ll receive a 401 response, indicating unauthorized access to the requested endpoint.

Response Structure

Each endpoint, regardless of the request’s outcome, adheres to a well-defined response structure that promotes clarity and predictability. This structure consists of two primary components: the ‘data’ object and the ‘metadata’ object.

  • data (When Applicable): When an endpoint returns response data, it is enclosed within the ‘data’ object, which is presented as a JSON object.
  • metadata: Contains descriptive information about the response, providing a general overview of the response.

Response Scenarios

  1. Success with response data:
{
  "data": {
    "property": "value",
    "property-2": true,
    "property-3": 123
  },
  "metadata": {
    "errors": [],
    "success": true
  }
}
  1. Success without response data:
{
  "metadata": {
    "errors": [],
    "success": true
  }
}
  1. Error Response (400 Bad Request):
{
  "metadata": {
    "errors": [
      {
        "message": "This Resource does not exist or may be deleted or You don't                         have access",
        "sysCode": "1005",
        "parameter": ""
      }
    ],
    "success": false
  }
}

Authentication

In this section, you will learn how to authenticate your External System with ROSAS, ensuring secure access to privileged endpoints.

POST Generate Client Access Token for External System

This endpoint is used by External System to generate an access token required for authentication in various protected endpoints across the API. The access token serves as a secure authorization mechanism for accessing privileged resources. Details and Example

Tenant Management

Tenant management is crucial for providing customized experiences within the ROSAS platform. This section covers various operations related to tenant management.

POST Create Tenant

This endpoint is used to create a new tenant. Details and Example

POST Create Super Admin

This endpoint is used to create a new super admin for the ROSAS System. Details and Example

POST Send Creation Request

This endpoint is used by External System to inform the ROSAS System that the tenant’s resources have been successfully created and activated. Details and Example

POST Send Activation Request

This endpoint is used by External System to inform the ROSAS System that the tenant’s resources have been successfully created and activated. Details and Example

POST Send Deactivation Request

This endpoint is used by External System to inform the ROSAS System that the tenant’s resources have been successfully created and activated. Details and Example

GET Get All Tenants

This endpoint empowers the external system to inquire about the status of all tenants. Details and Example

GET Get Tenant

This endpoint empowers the external system to inquire about the status of a specified tenant by utilizing the tenant’s name as a parameter. Details and Example

POST Set the tenant as Created

This endpoint is used by External System to inform the ROSAS System that the tenant’s resources have been successfully created and activated. Details and Example

POST Set the tenant as Active

This endpoint is used by External System to inform the ROSAS System that the tenant’s resources have been successfully activated. Details and Example

POST Set the tenant as Inactive

This endpoint is used by External System to inform the ROSAS System that the tenant’s resources have been successfully deactivated. Details and Example

POST Set the tenant as Failure

This endpoint is used by External System to inform the ROSAS System that the tenant’s resources have been successfully deactivated. Details and Example

POST Set the tenant as Deleted

This endpoint is used by External System to inform the ROSAS System that the tenant’s resources have been successfully deleted. Details and Example

POST Upsert Tenant’s Metadata

This endpoint allows the external system to store custom metadata associated with the product’s tenant. Details and Example

GET Get Tenant’s Status

This endpoint empowers the external system to inquire about the status of a specified tenant by utilizing the tenant’s name as a parameter. Details and Example

GET Get Tenant’s Metadata

Via this endpoint, the external system obtains the capability to access descriptive data (metadata) linked to a designated tenant. Details and Example

POST Set Subscription As Upgrade Applied Done

This endpoint is used by External System to inform the ROSAS System that the tenant’s resources have been successfully deactivated. Details and Example

Plans

GET Get Plans List

This endpoint empowers the external system to inquire about the status of a specified tenant by utilizing the tenant’s name as a parameter. Details and Example

Specifications

GET Get Specifications List

This endpoint empowers the external system to inquire about the status of a specified tenant by utilizing the tenant’s name as a parameter. Details and Example

← Product Warning Tab
Integrating with RoSaaS Webhooks →