Get Started!

The Kalmar APIs offer a wide range of capabilities, including authentication, device management, and data retrieval. These APIs not only enable seamless integration with other systems but also provide the flexibility to connect and analyze data with advanced platforms such as PowerBI or utilize them in conjunction with Grafana. This allows users to leverage the power of these external systems for in-depth data analysis or visualization purposes. Kalmar Energi APIs thus serve as a versatile toolset, facilitating easy integration and enhancing the overall functionality and usability of management solutions. However, this concise documentation serves as a brief guide to efficiently initiate the utilization of the most relevant APIs, enabling users to access the identical data that is streamed from the nodes and visualized within Stadshubben. In essence, it provides a succinct overview of the authentication process, token acquisition, and retrieval of nodes' data through the APIs.

Tools for Getting Started

In the realm of API development, the selection of tools can profoundly shape your path towards efficiency and success. The right tools empower you to navigate the complexities with finesse, enabling you to deliver robust and reliable APIs. Here, we present a selection of tools that resonate with the spirit of seamless development and thorough testing:

  • Postman: Simplifying API Testing

    Postman stands as one of the most user-friendly tools for API testing and development. With Postman, you can easily send requests to our APIs, observe responses, and validate the correctness of the data and functionality. Its intuitive interface allows you to create and organize collections of API requests, making it effortless to manage and execute tests. For more information, refer to the following link.

  • Visual Studio Code (VS Code): A Versatile Companion

    Visual Studio Code, commonly referred to as VS Code, is more than just a code editor. It offers a multitude of extensions and features that can greatly enhance your API testing endeavors. With extensions like REST Client, you can craft and send HTTP requests directly from within VS Code, enabling you to test your APIs without needing to switch between applications. For more information, refer to the following link.

  • Paw: API Development and Testing for Mac

    Paw is a macOS-native tool designed for API development and testing. It provides a user-friendly interface for crafting complex API requests, handling authentication, and generating client code snippets. For more information, refer to the following link.

  • Other Tools

    Insomnia: Versatile API Debugging and Testing, SwaggerHub: Design, Document, and Test APIs, and SoapUI: Comprehensive API Testing. The choice of tools should align with your team's workflow and the needs of your audience. Prioritize tools that facilitate collaboration, maintainability, and user-friendly development.

Authentication

This process is effective from 01-11-2023

When integrating Kalmar Energi's APIs with external systems or retrieving data through the APIs, authentication is required. To acquire the authentication token, one should conduct the authentication via HTTPS Request to call the below endpoint, with the following information in the Request, only the email and password fields require user input, while the remaining fields remain unchanged. The required information from the user is limited to first two fields, where they need to provide their email address and password. The remaining fields, which are unaffected, should be left unaltered or populated with the appropriate default values as specified in the authentication procedure:

Request Body

The above is merely a straightforward illustration, serving primarily for demonstration purposes. While JSON offers a clear and intuitive representation, the actual request body should be in the form of x-www-form-urlencoded, as shown in the following example. Hence, the Request Body must be sent as a x-www-form-urlencoded:

The "realm" value within the URL is derived from your organization's domain. For instance, at Kalmar Energi, the email format is: firstName.lastName@kalmarenergi.se. Here, "kalmarenergi" constitutes the realm value, leading to a modification in the URL accordingly:

Key Point

Please note, the use of x-www-form-urlencoded is applicable exclusively for authentication purposes. This implies that it is not applicable for the APIs, where JSON is utilized for API consumption.

If your domain includes a sub-domain (can be noticed by the presence of at least one dot), there will be a variation in the realm value. Consider an organization whose email addresses include a subdomain, such as firstName.lastName@kalmar.energi.se. In this instance, the realm value adjusts to "kalmar-energi", subsequently altering the URL:

Response

Below is an example of a response body:

Request Body

The above is merely a straightforward illustration, serving primarily for demonstration purposes. The Request Body must be sent as a x-www-form-urlencoded for refreshing the token.

Refreshing The Authentication Token

To continue accessing protected resources, it will be necessary to refresh the token. The token refresh process will generate a new authentication token, providing an additional time of access to the API. By periodically refreshing the token before it expires, uninterrupted access to the desired resources can be maintained. To refresh the token, you must call the below endpoint, with the following information in the Request, the user needs to provide the required information for the first field only, which is the refresh token. This refresh token is obtained in the response when making a prior call to the corresponding endpoint to acquire an authentication token. The remaining fields, should be left unaltered:

Authorization header

The bearer token is then included in the Request Headers when making a call to the following endpoint:

Authentication - Deprecated!

This process is deprecated, effective from 01-11-2023, and will cease to be in use after 31-01-2024.

When integrating Kalmar Energi's APIs with external systems or retrieving data through the APIs, authentication is required. To acquire the authentication token through the Kalmar Energi’s APIs, utilize the Customer Identity API, hence, one should conduct the authentication via HTTPS Request to call the below endpoint, with the following information in the Request, only the email and password fields require user input, while the remaining fields remain unchanged. The required information from the user is limited to first two fields, where they need to provide their email address and password. The remaining fields, which are unaffected, should be left unaltered or populated with the appropriate default values as specified in the authentication procedure:

Refreshing The Authentication Token

To continue accessing protected resources, it will be necessary to refresh the token. The token refresh process will generate a new authentication token, providing an additional time of access to the API. By periodically refreshing the token before it expires, uninterrupted access to the desired resources can be maintained. To refresh the token, you must call the below endpoint, with the following information in the Request, the user needs to provide the required information for the first field only, which is the refresh token. This refresh token is obtained in the response when making a prior call to the corresponding endpoint to acquire an authentication token. The remaining fields, should be left unaltered:

Response Status Code

Our APIs use status codes to express the outcome of a reques. These status codes follow the standard HTTP Protocol and are classified into different ranges, each carrying a specific meaning:

  1. Successful (2xx): These codes indicate that the request was successful, and the server processed it as intended.

    • 200 OK: The request was successful, and the server has returned the requested data.

    • 201 Created: The request was successful, and a new resource was created as a result.

    • 204 No Content: The request was successful, but there's no data to send in response (commonly used for DELETE requests).

  2. Client Errors (4xx): These codes indicate that there was an error on the client's part.

    • 400 Bad Request: The server could not understand the request due to malformed syntax or other client-side errors.

    • 401 Unauthorized: Authentication is required, and the credentials provided were either missing or invalid.

    • 403 Forbidden: The client does not have permission to access the requested resource.

    • 404 Not Found: The requested resource does not exist on the server.

  3. Server Errors (5xx): These codes indicate that there was an error on the server's part.

    • 500 Internal Server Error: A generic error message indicating that something went wrong on the server.

    • 502 Bad Gateway: The server, while acting as a gateway or proxy, received an invalid response from the upstream server.

    • 503 Service Unavailable: The server is currently unable to handle the request due to temporary overloading or maintenance.

Understanding these HTTP status codes allows developers to quickly diagnose and troubleshoot issues when working with APIs. They serve as a standardized communication mechanism between clients and servers, ensuring efficient and reliable interactions.


Request Example

For instnace, to retrieve comprehensive information about all nodes, including Node Id, Brand Id, Model Id, Connector Id, Last Message, LoRa Profile, Channels, and associated objects with their respective details, one can utilize this endpoint:

Response Payload: Pagination, Structure, and Syntax Explained

The response payload for the previous request example will bear a resemblance to this payload in principle. This response payload exemplifies a structured dataset conforming to a pagination paradigm, an approach often employed to manage large datasets efficiently. Let's break down the default components to understand the pagination, structure, and syntax it employs. Here is an example of a Response Payload:

This response payload exemplifies a structured dataset conforming to a pagination paradigm, an approach often employed to manage large datasets efficiently. Let's break down the default components to understand the pagination, structure, and syntax it employs:

  • pageIndex: Denotes the current page index in the paginated result set, starts from1.

  • totalPages: Represents the total number of pages available for the entire dataset.

  • pageSize: Specifies the number of items displayed per page.

  • count: Indicates the total count of items within the current page.

  • hasPrevious: A boolean flag signaling the presence of a previous page.

  • hasNext: A boolean flag indicating the existence of a subsequent page.

  • items: A collection comprising the data items specific to the requested resources, such as Nodes and their affiliated and interrelated objects, organized as nested arrays.

Additionally, the Response Payload is a JSON object that conforms to standard JSON syntax, with key-value pairs enclosed within curly braces ({}) and arrays denoted by square brackets ([]).

RESTful Architecture!

Our APIs are built upon the RESTful architecture, meticulously embracing the core principles of REST (Representational State Transfer). This approach exemplifies a robust framework that prioritizes efficiency, scalability, and simplicity in communication between systems.

To illustrate this with an example, consider the payload in the previous response. It becomes evident that the response not only contains the primary resources but also seamlessly incorporates their interconnected or related resources. This encapsulates the essence of REST's interlinked design philosophy, allowing for comprehensive and interconnected data representation. Through such meticulous orchestration, our APIs facilitate a cohesive and harmonious interaction, optimizing the transfer of information and enhancing the overall user experience.

Moreover, our APIs offer versatile sorting mechanisms that empower users to arrange resources based on their preferences, be it in ascending or descending order. This functionality extends to enabling users to filter resources through multiple fields, enhancing precision in information retrieval.

Furthermore, the capability to narrow down resource ranges is seamlessly integrated into our APIs. By specifying parameters like creation date, update date, or report date, users gain the ability to precisely limit the scope of resources they interact with.

In essence, our APIs present a robust trifecta of features: sorting, filtering, and resource limitation. This array of capabilities allows users to tailor their interactions precisely as desired, creating a dynamic and highly customizable experience for managing and utilizing resources effectively.

Review the following illustrations featuring different API endpoints:

  1. Base URL: https://api.kalmarenergi.se/device/v2/nodes

    • This is the base URL of the API endpoint we are accessing.

  2. Query Parameters:

    • query: This parameter allows us to search for devices based on a specific query; name, decription, etc. In the provided URL, it seems to be empty, indicating that we're not applying any specific filtering query.

    • pageIndex: This parameter determines which page of results we're requesting. In the URL, it's set to 1, indicating that we want to retrieve results from the first page.

    • pageSize: This parameter defines the number of items (devices) we want to retrieve per page. In the URL, it's set to 50, meaning we want to fetch 50 devices per page.

    • sortBy: This parameter specifies the property by which the results should be sorted. In this case, it's set to Id, indicating that we want to sort the devices based on their ID.

    • sortDescending: This parameter determines the sorting order. If set to false, it means we want the results in ascending order based on the sorting property (Id in this case).

  1. Base URL: https://api.kalmarenergi.se/device/v2/nodes

    • This is the foundational URL for the API endpoint we wish to access.

  2. Query Parameters:

    • query: This parameter permits us to filter devices based on a specific query term. In the URL we've provided, it is set to "sam", indicating that we're seeking devices with a relationship to the term "sam", whether a device is named "sam," contains the term "sam," or includes the term "sam" within another field.

    • pageIndex: This parameter determines which page of results we're interested in. In the URL, it's set to 1, signifying our request for data from the first page.

    • pageSize: This parameter dictates the number of items (devices) we want to receive per page. In the URL, it's set to 50, indicating we'd like to retrieve up to 50 devices per page.

    • sortBy: This parameter designates the property by which the results should be sorted. In this instance, it's set to Name, indicating our preference to arrange the devices based on their Names.

    • sortDescending: This parameter specifies the sorting order. When set to true, it signifies that you desire the results in descending order based on the sorting property (Name in this case).

  1. Base URL: https://api.kalmarenergi.se/device-data/v1/message-values

    • This is the primary URL of the API endpoint used for retrieving message values.

  2. Query Parameters:

    • nodeId: This parameter is a UUID and it specifies the unique identifier of the device from which we want to fetch message values. In the URL, it's set to 8ec3a890-4b1d-4eac-9aeb-6c31dd06c6a2, indicating the device with this ID.

    • pageIndex: This parameter determines which page of results we're requesting. In this case, it's set to 1, indicating our request for data from the first page.

    • pageSize: This parameter indicates the number of items (message values) you want to retrieve per page. In this URL, it's set to -1, signifying that you want to retrieve all available items without limiting the number. Note, if the pageSize is set to 0, no items will be returned; however, the result counts will still be provided. On the other hand, if the pageSize is greater than 0, the user will receive the requested items. If the value is -1, then all items will be returned.

    • sortBy: This parameter specifies the property by which the results should be sorted. In this instance, it's set to ReportedAt, indicating our preference to sort the message values by the time they were reported.

    • sortDescending: This parameter defines the sorting order. When set to false, it means we want the results in ascending order based on the sorting property (ReportedAt in this case).

    • channelIds: This parameter lists the unique identifiers of the channels from which we want to retrieve message values. In the URL, there are several instances of this parameter, each with a different value. This indicates that we're interested in values from multiple channels. Please note that a node, which represents a device, can encompass several channels contingent on the Brand and Model. It's possible to fetch values for all channels associated with this device or a subset of them, determined by the parameters we specify within the channelIdsfield.

    • startDate: This parameter signifies the starting date and time from which we want to retrieve message values. In the URL, it's set to 2023-08-08T08:17:47.499Z, indicating we're looking for values reported on or after this date and time (in UTC).

Core API Highlights

The listed APIs can bear substantial significance for users who are striving to adeptly oversee their devices and promptly interact with the APIs. As such, we've included concise descriptions of these APIs here. This introductory information is designed to guide users in the right direction, streamlining their experience and facilitating easy engagement with their devices.

Customer Identity API

The Customer Identity API serves as the cornerstone for authentication, token retrieval, and token refreshing. Consequently, prior to utilizing the APIs, authentication through this API is imperative to establish the user's identity.

Device API

The Device API enables users to oversee their devices, encompassing device details, status, and the retrieval of comprehensive device-related information. This encompasses attributes like brand, model, channels, and connectors associated with the devices.

Device Alarm API

The Device Alarm API enables users to effectively handle alarms and their corresponding recipients. These alarms are intricately linked to devices. Should a user wish to create an alarm triggered by a specific condition, such as when a device's channel reaches a predefined threshold value, this API facilitates the process.

Device Data API

The Device Data API empowers users to retrieve data from the active nodes, making it a means to acquire device-related data as well.