1. Getting Started

This guide walks you through the steps to make your first call with the V5 Java API client.

Quick Start (60 seconds)

Three things you need

Item	Value	Where to get it
Server address	http://<server-ip>:80 (https://<server-ip>:443 for TLS)	REST API endpoint. :7443 is for the admin console only, so use 80/443 for the API
Account ID	e.g. api	User account for API calls
Token	UUID format	Issue it for that account under Security Management → API Authentication Token (/token/index) in the console → Security Settings · Security Management

With just these three values, the single block below is enough for your first call.

import java.util.List;
import plantpulse.api.v5.APIClient_V5;
import plantpulse.api.v5.dto.response.SiteResponseV5;

try (APIClient_V5 client = new APIClient_V5(
        "HTTP", "100.68.69.41", 80, "api", "<issued-token>", false)) {
    client.connect();                                       // 인증
    System.out.println(client.system().ping().isPing());    // → true
    for (SiteResponseV5 s : client.site().list())           // 사이트 목록
        System.out.println(s.getSite_id() + " — " + s.getSite_name());
}

If this block prints true and a site list, you are ready to go. Sections 1.1 through 1.7 below describe each step in detail.

1.1 Adding the Dependency

Add the JAR file to your classpath.

# 빌드 (Gradle + Java 21)
cd plantpulse-api
./gradlew build

The build artifacts are generated in target/.

File	Purpose
target/plantpulse-api.jar	For integrating into an existing project along with its dependencies

1.2 Creating the Client

Pass the options directly to the APIClient_V5 constructor.

import plantpulse.api.v5.APIClient_V5;

APIClient_V5 client = new APIClient_V5(
        "HTTPS",                                       // 프로토콜: "HTTP" 또는 "HTTPS"
        "100.68.69.41",                                // host
        443,                                           // port (REST API: 80=HTTP, 443=HTTPS)
        "api",                                         // user_id
        "19ba7a54-1132-49f2-967e-3c6f5cd989a0",        // token (api_key 발급용)
        false);                                        // debug

client.connect();          // 인증 + HTTP 클라이언트 초기화

// ... API 호출 ...

client.close();            // 종료

Constructor Parameters

Parameter	Type	Description
protocol	String	"HTTP" or "HTTPS"
host	String	Server host or IP
port	int	Server port
user_id	String	Authentication account ID
token	String	Issued token (UUID format)
debug	boolean	Debug logging of HTTP requests and responses

Authentication flow: When connect() is called, the client internally obtains an api_key using user_id + token, and automatically includes that key in the headers of all subsequent calls. You never need to handle it yourself.

1.3 First API Call — ping & Site List

import java.util.List;
import plantpulse.api.v5.APIClient_V5;
import plantpulse.api.v5.dto.response.SiteResponseV5;
import plantpulse.api.v5.dto.response.SystemPingResponseV5;

public class FirstCall {
    public static void main(String[] args) throws Exception {

        try (APIClient_V5 client = new APIClient_V5(
                "HTTP", "100.68.69.41", 80, "api",
                "19ba7a54-1132-49f2-967e-3c6f5cd989a0", false)) {

            client.connect();

            // 1) 서버 헬스체크
            SystemPingResponseV5 ping = client.system().ping();
            System.out.println("Server alive: " + ping.isPing()
                + " (v" + ping.getVersion() + ")");

            // 2) 사이트 목록 (typed DTO 리스트)
            List<SiteResponseV5> sites = client.site().list();
            for (SiteResponseV5 s : sites) {
                System.out.println(s.getSite_id() + " — " + s.getSite_name());
            }
        }
    }
}

Execution result:

Server alive: true (v5.0)
SITE_00001 — 대전 1공장
SITE_00002 — 천안 2공장

1.4 try-with-resources Pattern

APIClient_V5 implements AutoCloseable. Using try-with-resources is recommended.

try (APIClient_V5 client = new APIClient_V5(proto, host, port, user, token, false)) {
    client.connect();
    // ... API 호출 ...
}
// close() 자동 호출 — HTTP 커넥션 정리

1.5 The 13 Services at a Glance

Immediately after connect(), you can access every domain through the service methods below (lazily initialized).

client.system()    // 헬스체크
client.site()      // 사이트(공장)
client.customer()  // 고객
client.employee()  // 직원
client.product()   // 제품
client.asset()     // 자산 계층 (Area → Line → Equipment)
client.opc()       // OPC 데이터 채널
client.tag()       // 태그(데이터 포인트)
client.alarm()     // 알람
client.order()     // 작업지시
client.calendar()  // 일정
client.path()      // 자산 경로
client.flow()      // Flow / Flow Node

1.6 Standard V5 Method Signature Patterns

All domain services follow a consistent method pattern. Only the domain name differs; usage is identical.

Pattern	Return type	Return value on failure	Description
create(req)	*ResponseV5	null	Register
update(id, req)	*ResponseV5	null	Full update
delete(id)	boolean	false	Delete
get(id)	*ResponseV5	null	Single-record lookup
list()	List<*ResponseV5>	empty list	Full list
exists(id)	boolean	false	Existence check
count()	long	0	Count

⚠️ No exceptions are thrown. Communication errors and server ERROR responses are returned as the safe default values listed above. Check the log or BaseServiceV5.getErrorCode(env) for the cause of the error. See Response Format and Error Handling for details.

1.7 Debug Mode

If you pass true as the last constructor argument, HTTP requests and responses are printed to the console.

APIClient_V5 client = new APIClient_V5(
        "HTTP", "100.68.69.41", 80, "api", TOKEN, true);  // debug=true

Example output:

[V5] GET https://server/api/v5/site headers={api_key=ab****cd}
[V5] response: 200 {"_status":"OK","data":[{"site_id":"SITE_00001",...}]}

Next Steps

• Domain ID Rules — Read this next. ID prefix validation is enforced.
• Response Format and Error Handling — Error code mapping and safe handling patterns
• Site Service — Creating your first master data