7. Northbound API Specification

7.1. About Northbound API Specification

OVSE 플랫폼은 인증, 회사 및 단말 관리, 통계를 위한 Northbound API를 제공합니다.

7.2. REST API

OVSE northbound는 다음과 같은 REST API를 제공합니다. 상세한 내용은 OVSE Document 내용을 참고하시기 바랍니다.

구분	설명	Method	URL
Auth	- 로그인 - 토큰 갱신 - 비밀번호 변경 - 임시비밀번호 변경 - 사용자 이메일 검색	POST POST POST POST POST	/api/auth/login /api/auth/token /api/auth/changePassword /api/auth/resetPasswordByEmail /api/auth/findUserEmail
Company	- 회사 정보 등록 - 회사 정보 조회 - 회사 정보 수정 - 회사 삭제 - 내 회사 정보 조회 - 특정 Service Type에 속하는 회사 리스트 조회 - 등록된 전체 회사 수 조회 - 특정 Service Type에 속하는 회사의 수 조회 - 회사 관리자 등록 - 회사 관리자 수정 - 회사 관리자 삭제 - 회사 관리자 리스트 조회 - 소유한 단말 리스트 조회 - 특정 회사 모든 단말에 메시지 전달	POST GET PUT DELETE GET GET GET GET POST PUT DELETE GET GET POST	/api/ovs/v1/company /api/ovs/v1/company/{companyId} /api/ovs/v1/company/{companyId} /api/ovs/v1/company/{companyId} /api/ovs/v1/company/me /api/ovs/v1/companies /api/ovs/v1/companies/all /api/ovs/v1/companies/cnt /api/ovs/v1/company/{companyId}/admin /api/ovs/v1/company/{companyId}/admin/{adminId} /api/ovs/v1/company/{companyId}/admin/{adminId} /api/ovs/v1/company/{companyId}/admins /api/ovs/v1/company/{companyId}/devices /api/ovs/v1/company/{companyId}/message
Device	- 단말 등록 - SerialNo로 단말 조회 - 단말 정보 조회 - 단말 정보 수정 - 단말 삭제 - 전체 단말 리스트 조회 - 특정 Service Type에 속하는 단말의 수 조회 - 소유한 전체 단말 수 - 단말별 메시지 전달	POST GET GET PUT DELETE GET GET GET POST	/api/ovs/v1/device /api/ovs/v1/device /api/ovs/v1/device/{deviceId} /api/ovs/v1/device/{deviceId} /api/ovs/v1/device/{deviceId} /api/ovs/v1/devices /api/ovs/v1/devices/cnt /api/ovs/v1/devices/owned/cnt /api/ovs/v1/device/{deviceId}/message
Stats	- 특정 회사 모든 단말의 기간별 이벤트 통계 - 특정 단말 기간별 이벤트 통계	GET GET	/api/ovs/v1/company/{companyId}/statistics/event /api/ovs/v1/device/{deviceId}/statistics/event

[API 리스트3]

구분	설명	Method	URL	SA
Auth	- 로그인 - 토큰 갱신 - 비밀번호 변경 - 임시비밀번호 변경 - 사용자 이메일 검색	POST POST POST POST POST	/api/auth/login /api/auth/token /api/auth/changePassword /api/auth/resetPasswordByEmail /api/auth/findUserEmail	O O O O O
Company	- 회사 정보 등록 - 회사 정보 조회 - 회사 정보 수정 - 회사 삭제 - 내 회사 정보 조회 - 특정 Service Type에 속하는 회사 리스트 조회 - 등록된 전체 회사 수 조회 - 특정 Service Type에 속하는 회사의 수 조회 - 회사 관리자 등록 - 회사 관리자 수정 - 회사 관리자 삭제 - 회사 관리자 리스트 조회 - 소유한 단말 리스트 조회 - 특정 회사 모든 단말에 메시지 전달	POST GET PUT DELETE GET GET GET GET POST PUT DELETE GET GET POST	/api/ovs/v1/company /api/ovs/v1/company/{companyId} /api/ovs/v1/company/{companyId} /api/ovs/v1/company/{companyId} /api/ovs/v1/company/me /api/ovs/v1/companies /api/ovs/v1/companies/all /api/ovs/v1/companies/cnt /api/ovs/v1/company/{companyId}/admin /api/ovs/v1/company/{companyId}/admin/{adminId} /api/ovs/v1/company/{companyId}/admin/{adminId} /api/ovs/v1/company/{companyId}/admins /api/ovs/v1/company/{companyId}/devices /api/ovs/v1/company/{companyId}/message	O O O | O O O O O O O O O O O
Device	- 단말 등록 - SerialNo로 단말 조회 - 단말 정보 조회 - 단말 정보 수정 - 단말 삭제 - 전체 단말 리스트 조회 - 특정 Service Type에 속하는 단말의 수 조회 - 소유한 전체 단말 수 - 단말별 메시지 전달	POST GET GET PUT DELETE GET GET GET POST	/api/ovs/v1/device /api/ovs/v1/device /api/ovs/v1/device/{deviceId} /api/ovs/v1/device/{deviceId} /api/ovs/v1/device/{deviceId} /api/ovs/v1/devices /api/ovs/v1/devices/cnt /api/ovs/v1/devices/owned/cnt /api/ovs/v1/device/{deviceId}/message	O O O O O O O O O
Stats	- 특정 회사 모든 단말의 기간별 이벤트 통계 - 특정 단말 기간별 이벤트 통계	GET GET	/api/ovs/v1/company/{companyId}/statistics/event /api/ovs/v1/device/{deviceId}/statistics/event	O O

SA: System Admin, CA: Company Admin, D: Director

7.3. Entity Model and Registration

REST API에서는 다음과 같은 Entity들이 정의되어 있으며, 세부 데이터 모델과 등록 방법은 :ref:`5. 구성요소(Entity) 등록 <entity-registration>`__ 내용을 참고하시기 바랍니다.

• Company
• Device
• Director

7.4. 인증 Authentication API

OVSE Northbound API 사용시 해당 API에 맞는 authentication API를 통해 token을 부여받고, 이를 header에 포함하여야 합니다.

[표 추가: company admin과 director간 호출가능한 API 분류 - 혹은 표에 추가] [ 혹은 company admin만 호출가능한 API 명시]

token을 받기 위한 authentication API는 아래와 같습니다.

POST	/api/auth/login

• Header

option	Type	Default	Description
Content-Type	string	application/json	content type

• Body

Key	Type	Description
username	string	로그인할 아이디(이메일)
password	string	패스워드

• Example Code

Request

content-type:"application/json"

{
    "username":"example@example.com",
    "password":"1234"
}

Response (code: 200)

{
    "token":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…",
    "refreshToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1…"
}

요청이 성공하면(code:200) Response에서 인증 토큰으로 사용할 token 필드를 얻을 수 있습니다. Token 필드는 HTTP Header에 “X-Authorization”의 값으로 사용되며 로그인할 때마다 변경됩니다. 토큰이 있으면 해당 계정에 접근할 수 있으므로 외부 유출이 안되도록 주의해야 합니다. |br| 토큰을 얻었으면 회사 정보 등록 API를 통해 서비스를 등록합니다. |br|

7.5. 정보 조회 API

7.5.1. 회사 정보 조회

등록된 회사의 정보를 조회하는 API 입니다. 회사정보를 조회하기 위해서는 회사 Admin 계정으로 인증받은 token이 필요합니다. 관리자(Director) 계정으로는 회사 정보를 조회할 수 없습니다.

• Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

• Body

Key	Type	Description
N/A	N/A	N/A

• Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

Response (code: 200)

{
    "id": {
        "id": "4813f210-73ab-11ea-ac0c-d950be57c747"
    },
    "createdTime": 1585699007148,
    "name": "test_companyname_ovse2",
    "serviceType": "test_servicetype_ovse2",
    "picPasswd": "null",
    "picName": "createcompanynam2e",
    "picPhone": "010-1111-1234",
    "picEmail": "test_servicetype_ovse2@sktint.com",
    "picDivision": "team1",
    "description": "additional description",
    "tokenPrefix": "enh03"
}

회사ID가 등록되어있고, token이 유효한 경우 정상적으로 조회할 수 있습니다. 나의 소속 회사 ID를 모르는 경우, 소속 회사 조회 API로 검색 가능합니다. |br|

7.5.2. 내 회사 정보 조회

나의 계정정보와 내가 속한 회사의 Company ID를 조회하는 API 입니다.

GET | /api/ovs/v1/company/me

• Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

• Body

Key	Type	Description
N/A	N/A	N/A

• Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

Response (code: 200)

token이 유효한 경우 정상적으로 조회할 수 있습니다.

|br|

7.5.3. 회사 관리자(Director) 리스트 조회

7.5.4. 단말 정보 조회

단말 ID를 통해 단말 정보를 조회하는 API 입니다.

GET | /api/ovs/v1/device/{deviceId}

• Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

• Body

Key	Type	Description
N/A	N/A	N/A

• Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

Response (code: 200)

token이 유효한 경우 정상적으로 조회할 수 있습니다.

7.6. 정보 수정 API

7.6.1. 회사 정보 수정

7.6.2. 단말 정보 수정

7.6.3. 관리자 정보 수정

7.7. 이벤트 통계 API

7.7.1. 통계1

7.7.2. 통계2

7.7.3. 통계3