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

[yunkon-kim]

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

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

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

(Spider에서 살펴본 사항)

• https://github.com/cloud-barista/cb-spider/blob/master/api-runtime/rest-runtime/VPC-SubnetRest.go
• https://github.com/cloud-barista/cb-spider/blob/master/cloud-control-manager/cloud-driver/interfaces/resources/VPCHandler.go
• https://documenter.getpostman.com/view/24786935/2sA3dxDXEy#9b77c207-e98c-4b6e-b6f5-4a2c04286c41

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

(API docs)

(API docs)

(Tags for go struct fields)

[powerkimhub]

@yunkon-kim

• 현재는 명확하게 표시된 가이드는 없는 상태입니다.

  • 추후 개선하도록 하지요.

• 현재 VPC/Subnet의 경우 API 규격/예제 링크에 포함된 예제에 설정된 값들을 Required 인자로 보시면 되겠습니다.

• 참고: 코드내 입력 값 인자 Validation 부분(기본이 Required, Empty 허용 인자)
  

  cb-spider/api-runtime/common-runtime/VPC-SubnetManager.go

  Lines 349 to 355 in f9e8907

  	emptyPermissionList := []string{
  	"resources.IID:SystemId",
  	"resources.VPCReqInfo:IPv4_CIDR", // because can be unused in some VPC
  	"resources.SubnetInfo:Zone", // because can be unused in some Zone
  	"resources.KeyValue:Key", // because unusing key-value list
  	"resources.KeyValue:Value", // because unusing key-value list
  	}

[특이 사항]

• 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]

@powerkimhub

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

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

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

[powerkimhub]

@yunkon-kim

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

[yunkon-kim]

@powerkimhub

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

[powerkimhub]

@yunkon-kim

• 넵, 캄사합니다.

[yunkon-kim]

@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]

@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]

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

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

[powerkimhub]

@yunkon-kim

• 👍

[powerkimhub]

@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