Is there any reference to check if a property in an API req/res body is required or optional?

yunkon-kim commented 3 months ago

다음주부터 Tumblebue에서 네트워크 Feature 개선 작업을 계획하고 있습니다.

Spider VPC, Subnet 관련 API 문서와 Request/response body로 보이는 struct 까지 살펴 보았으나 Req/res body의 모든 properties와 필수/선택 항목 여부를 파악하기 어려웠습니다...

관련하여 참고할만한 레퍼런스가 있을지 문의드립니다.

(Spider에서 살펴본 사항)

예를 들어, 다음과 자료가 필요한 상황입니다. 형태는 상관 없을 것 같고요. 정보/표시만 확인되면 좋을 것 같습니다.

(API docs)

(Tags for go struct fields)

powerkimhub commented 3 months ago

@yunkon-kim

현재는 명확하게 표시된 가이드는 없는 상태입니다.
- 추후 개선하도록 하지요.
현재 VPC/Subnet의 경우 API 규격/예제 링크에 포함된 예제에 설정된 값들을 Required 인자로 보시면 되겠습니다.
참고: 코드내 입력 값 인자 Validation 부분(기본이 Required, Empty 허용 인자) https://github.com/cloud-barista/cb-spider/blob/f9e890756c6bd6e85d39e2febed58a2318ba0203/api-runtime/common-runtime/VPC-SubnetManager.go#L349-L355

[특이 사항]

VPC CIDR: 예외적으로 'Empty'를 허용합니다.
- 사유: 3.제공자원 링크에서 Type1 참고
IDTransformMode: Optional
- 현재는 Tumble 전용
- 참고: ID Transformation ON OFF Guide
Zone: Optional
- 아직 공식 배포 전, 배포되면 Optional
- 관련 자원: Subnet, Disk, MyImage (VM은 Subnet 선택이 Zone 선택)
TagList: Optional
- 아직 공식 배포 전, 배포되면 Optional
List/Get 계열 API: 현 이슈와 무관하지만, 2가지 호출 형식 제공
- 관련 예시: 아래 이미지 참고
- VPC 뿐만 아니라 모든 GET Method 호출에 적용

[참고] List/Get API 2가지 호출 형식 예시

yunkon-kim commented 3 months ago

@powerkimhub

자세히 설명해주셔서 감사합니다.

API 문서에 나타나는 properties 들은 기본적으로 required 이고,
emptyPermissionList에 있는 properties 들은 예외적으로 optional 이며,
IDTransformMode 와 같이 예외적인 properties 가 있는 것으로 이해하였습니다.

Spider 코드들을 파악하여 Tumblebug 네트워크 Featrue를 개선하는 방향으로 진행하겠습니다.

powerkimhub commented 3 months ago

@yunkon-kim

넵, 맞습니다.
현 이슈는 방안 마련 시까지 오픈 유지하겠습니다.

yunkon-kim commented 3 months ago

@powerkimhub

Tumblebug network feature 개선 작업의 선행 사항 작업으로, Spider network API 관련 코드를 분석하였고요. 이를 공유드립니다. 향후 API를 개선하실 때 참고 자료로 활용하시면 될 것 같습니다. (편집자 권한이 필요하시면 말씀해주세요.) : https://docs.google.com/spreadsheets/d/1ICPIiXAE7_zY6cS7BD-dMTSZNQOhdGZ79iPz4q6F9iU/edit?usp=sharing

powerkimhub commented 3 months ago

@yunkon-kim

넵, 캄사합니다.

yunkon-kim commented 3 months ago

@powerkimhub VPC/Subnet 관련 질문이 있어 여기에 문의 드립니다.

1. Subnet 관련 connectionName이 별도로 있는 것 인지 궁금합니다. : VPC + Subnet 생성시 사용한 connectionName을 Subnet 삭제 API에 사용했을 때 삭제 성공 했습니다. : AdminWeb 상에는 아래와 같이 나뉘어 있어 확인차 문의 드립니다.

2. 향후에 Subnet 조회 API를 제공하실 계획이 있으신지 문의 드립니다.

3. VPCInfo, SubnetInfo에서 Status 필드의 지원이 가능하신지 문의 드립니다. : 상태 조회 측면에서 2번과 연관성이 있는 부분입니다. : 현재는, VPC와 Subnet의 Status 정보가 KeyValueList를 통해 제공될 때가 있고 그렇지 않을 때가 있는 것으로 파악됩니다. : Tumblebug에서 vNet, subnet 제어시, CSP의 자원 상태 정보를 활용하는 것으로 생각하고 있습니다.

powerkimhub commented 3 months ago

@yunkon-kim

1. Subnet 관련 connectionName이 별도 존재 유무

자원별로 ConnecitonName이 별도로 존재하는 것은 아닙니다.
- 하나의 ConnectionName을 기준으로 자원을 생성/삭제한다고 보시면 되겠습니다.
ConnectionName은 csp-driver-credential-region-zone을 하나의 id로 관리해준다고 보면 됩니다.
- 즉, ConnectionName-1로 생성한 vpc/subnet은 ConnectionName-1로만 Read/Delete 가능합니다.
- ※ 참고: 관련하여 ConnectionName 외의 다른 Zone의 자원을 관리 가능한 Zone-based Control 추가 중입니다.
  - default zone: ConnectionName-1에 설정된 Zone
  - target zone: ConnectionName-1에 설정된 Region의 다른 Zone에 자원을 만들고 싶을 경우 사용자가 지정하는 Zone
  - target zone 설정을 제공하는 자원: subnet, vm, disk, myimage
  - Zone-based control 개발/시험 현황: 링크 참고
또한, 현재 버전은 ConnectionName 기반으로 Naming space가 관리 됩니다.
- 즉, conn1.vpc-01 존재시
  - conn1.vpc-01: 추가 불가
  - conn2.vpc-01: 추가 가능
  - conn2 이용시: conn1.vpc-01 read/write 불가
- ※ 관련 개선 계획 있습니다.
  - Connection이 다르더라도 credential 권한이 있다면 다른 connection에 존재하는 자원 crud 제공
  - Tumblebug 요청사항으로 추진 예정

2. Subnet 조회 API 제공 계획 관련

(1) 조회의 의미가 Spider에 등록된 Subnet 조회라면
- Get/List VPC API 반환 정보에 포함된 정보 활용을 제안 드립니다.
- 관련해서는 Tumblebug에서 Spider를 통해서 생성한 자원 정보는 TB 메타 정보에 관리 될 것이므로
  - TB 자체 metadb에서 검색이 빠를 듯합니다.
- 현재 Spider 수준에서는 관련된 추가 API 지원 계획은 없습니다.
(2) 조회의 의미가 Spider에 등록되지 않은 CSP에 존재하는 subnet 조회라면
- 이 경우에는 필요시 추가 가능합니다.

3. VPCInfo, SubnetInfo에서 Status 필드의 지원 가능 여부

이 경우에는 csp별 제공 현황 확인 필요합니다.
대대수 CSP가 제공할 경우 지원 가능합니다.
다만, 지원 우선 순위 및 기존 일정 상 시간이 좀 걸릴 수는 있습니다.

yunkon-kim commented 3 months ago

@powerkimhub 넵! 자세히 설명해주셔서 감사합니다.

1번에 대해서 앞으로 트래킹 하도록 하겠습니다.
2, 3번과 관련해서는 Tumblebug 네트워크 Feature를 조금 더 개선해 본 이후에 별도로 말씀드리겠습니다.

powerkimhub commented 3 months ago

@yunkon-kim

👍

powerkimhub commented 1 month ago

@yunkon-kim

여러 이슈가 섞여 있고,
어느 정도 해결된 듯하여 close 합니다.
관련된 추가 이슈 발생시 별도 이슈로 오픈 부탁드립니다.

Reference for API required or optional properties
- Supported Swagger-based API documentation since v0.9.4
API to get subnet information
- Added GetSubnet in v0.9.5

cloud-barista / cb-spider

Is there any reference to check if a property in an API req/res body is required or optional? #1291