Activator APIs

Intro

The API (Application Programming Interface) of our ERP is at the core of its extensibility and integration with other systems. By providing a well-defined set of access points, our API empowers developers to create custom modules, third-party applications, automate processes, and seamlessly synchronize data.

The APIs of Activator are designed to be flexible and scalable, allowing developers to create customized solutions that meet the specific needs of their users. They provide access to platform features, enabling developers to precisely select the features they need for their applications. Using Activator's APIs saves time and effort by allc'est bonowing you to focus on developing value-added features for your applications. They offer a simple and consistent way to access platform features, enabling you to create robust and scalable applications.
More broadly, in the integration of modern systActivator Api est bonems, APIs and web services play a crucial role by providing a standardized method for applications to exchange data and functionalities consistently. APIs and web services are therefore essential elements in the Activator ecosystem, enabling efficient communication between different components and optimal utilization of available resources. Their use ensures a seamless and consistent integration of applications and systems, thereby promoting efficiency and competitiveness for businesses utilizing the platform. In summary, APIs play a crucial role in the architecture of Activator and in the integration of modern systems, ensuring smooth communication and effective utilization of platform functionalities.

The APIs in Activator go beyond simply enabling access to the platform's features. They act as intelligent bridges, connecting different layers of the technological ecosystem. As catalysts for innovation, they foster collaboration between internal and external developers, thus enabling the creation of customized and scalable solutions. Activator's APIs transform traditional business processes into modern digital experiences, paving the way for new business models and increased operational agility. In short, they not only connect systems but also drive digital transformation by bringing new ideas to life and fostering continuous growth.

It's worth noting that our ERP data is distributed across two different database management systems: Microsoft SQL Server for the components and MongoDB for record data. This division allows us to optimize data management according to its specific characteristics. Explore this section to discover how to fully utilize our API and create tailor-made solutions that precisely meet your needs.

Environnements and URLs☁️

Activator APIs are available across three distinct environments:

• Development Environment (dev): Used for initial feature development and testing. 
• Testing Environment (test): Designed for comprehensive ERP testing before production deployment.
• Production Environment (pro): The primary environment where the ERP is operational for regular use by end users.

Feel free to explore these platforms, environments, and API capabilities to enhance your experience with ASM Activator.

API Documentation

Each API comes with detailed documentation accessible via the /swagger/index.html URL added to its base URL. For example, to access the documentation of the https://v2_modulesapi_dev.asmlogic.com API, simply visit https://v2_modulesapi_dev.asmlogic.com/swagger/index.html.

As can be seen, the documentation for each API is generated using Swagger. For more details about this tool, please visit their website at https://swagger.io.

Now, let's delve deeper into our APIs to see how they are formatted and structured. To do this, let's open https://v2_modulesapi_dev.asmlogic.com/swagger/index.html, where you'll find an interface similar to the one shown in the image below.

ℹ️ INFO:

The APIs' URLs are categorized in Swagger based on conceptual similarity and semantic proximity.

Regarding the URL structure for each request, there are two main components: the base URL and the API path. The base URL is the prefix leading to the chosen API type, in our case, it is https://v2_modulesapi_dev.asmlogic.com.  The path is the part highlighted in the image in Swagger, as shown above.

Breaking down the path, we find two distinct parts:

1. The first part (/api/tenants/{tenantId}) which always requires the recordId of the tenant for the request.
2. The second part, containing the specific path to the API with its parameters (/accesscontrol/roles).

To retrieve the mentioned tenantId in an API, using JavaScript (via a helper, driver, or contentProvider), it is stored in the global variable $activator and accessible through the tenantId property. To access it, simply provide $activator.tenantId.

Caution

For every request sent to the server, it's crucial to include an authentication token (bearer token) in the header to ensure the request's authenticity. This token is generated after the user, or an application has been authenticated. It's worth noting that this token expires after 2 hours, after which a new authentication will be required to continue accessing resources securely.

To retrieve the mentioned token in an API, in JavaScript (using a helper, driver, or contentProvider), it is stored in the global variable $activator and accessible via $activator.accesscontrol.jwt once authenticated.

Now that we've covered the crucial aspect of the authentication token for our API requests, let's shift our focus to the generic response model of these APIs to better understand how these interactions are structured.

Each API in Activator follows the same generic response model, which is as follows:

{
    "errors": [
        {
            "errorCode": 0,
            "description": "string"
        }
    ],
    "payload": true
}

In summary, the result of any request is a JSON object that has two main properties:

The errors property

The errors property is a collection of objects, either an array of strings. In the first case, the objects here represent specific information about the error. An error object also has two properties:

• errorCode: representing the error code
• description: containing much more detailed information about the error

Example 1: A request with an incorrect recordId for the tenant will result in this. Here, the errors field contains a collection of objects.

{
    "errors": [
        {
            "errorCode": 422,
            "description": "Invalid tenant identifier 'cbccf6d5-d4dd-4dfc-82af-a15bf90f5aae'"
        }
    ],
    "payload": null
}

 Example 2: A request with an invalid or incorrect token will result in this. Here, the errors field is an array of strings.

{
    "errors": [
        "Invalid security token"
    ],
    "payload": null
}

🗒️Note

Although most of the time, when the errors array contains an error, the payload is null, there may be exceptions where it also contains a non-null value. Therefore, it is recommended to always ensure that the errors array is empty before considering the results returned in the payload field

The payload property

The payload property is where the results of each request are returned. This field can contain different types of returned data: a string, an array of strings, an object, or a collection of objects.

Example 1: An API that performs an operation and returns true upon successful completion of the operation.

{
    "errors": [],
    "payload": true
}

Example 2: An API that creates a record and returns its recordId

{
    "errors": [],
    "payload": "22d4a0c5-3a7e-4252-97e9-38bb189c4e99"
}

Example 3: An API that performs a findOne (search for a record by its recordId) and returns the record.

{
    "errors": [],
    "payload": {
        "firstName": "John",
        "lastName": "Doe",
        "recordId": "22d4a0c5-3a7e-4252-97e9-38bb189c4e99"
    }
}

Example 4: An API that retrieves a list of members.

{
    "errors": [],
    "payload": [
        {
            "firstName": "John",
            "lastName": "Doe",
            "recordId": "22d4a0c5-3a7e-4252-97e9-38bb189c4e99"
        },
        {
            "firstName": "Sarah",
            "lastName": "Doe",
            "recordId": "05e61bee-58cf-4421-8f86-5e2668e0a8ca"
        },
        {
            "firstName": "Usman",
            "lastName": "Doe",
            "recordId": "19c0844c-9356-4968-b540-8dc147a87278"
        }
    ]
}

APIs Shortcuts🖱️

In our APIs, we have included functions (Promises) that act as JavaScript shortcuts for developers, making communication with requests quick and efficient. These functions are designed to simplify and accelerate the development process, providing developers with an efficient way to manage interactions with our APIs.

These Promises functions provided in our APIs are applicable to components such as helpers, drivers, and contentProviders.

The following list mainly comprises generic shortcuts for executing APIs from https://v2_modulesapi_dev.asmlogic.com  based on their method.

• Here, the path parameter refers the primary path described in the API documentation. For example: /api/tenants/{tenantId}/entities/{entityName}/records.
• The body parameter represents the model specific to the API to be sent.

In summary, the table presented provides a non-exhaustive list of API shortcuts in JavaScript. However, it is worth noting that there are also shortcuts specific to the APIs of each component, as well as shortcuts in C#. This diversity of features greatly facilitates interaction with our APIs, providing developers with a wide range of tools to enhance their development experience.