---
# System prepended metadata

title: Hubble API Schema

---

# Hubble API Schema
> 기획서 버전 1.1을 토대로 작성되었습니다.
> 작성자: @sion.fe @edward.happy @sam.rho
> 일시: 2020-12-17


## API

### ResponseProps

> 공통 response wrapper 포맷

```typescript
interface ResponseProps {
  message: 'success' | 'fail';
  code: number;
}
```

### Filter

> 검색 필터 공통 포맷

##### method
- GET
##### response
```typescript
interface SearchItem {
  id: number;
  name: string;
}

interface SearchList extends ResponseProps {
  list: SearchItem[];
}
```

#### ✅ 검색필터 - 서비스 항목 조회

##### path
- /search/service


#### ✅ 검색필터 - 지식그래프 항목 조회

##### path
- /search/graph
##### request
- serviceId

#### ✅ 검색필터 - 타입 항목 조회

##### path
- /search/type
##### request
- serviceId
- graphId
- typeId (optional)

#### ✅ 검색필터 - 프로퍼티 항목 조회

##### path
- /search/type
##### request
- serviceId
- graphId
- typeId

#### ✅ 검색필터 - 키워드

##### path
- /search/type
##### request
- serviceId
- graphId
- typeId
- keyword


### Entity

#### ✅ 최근 업데이트 entity 

##### path
- /entity/latestUpdate
##### method
- GET
##### request
##### response
```typescript
interface EntityItem {
  id: number;
  name: string;
  publishedAt: string;
  count: number;
  filter: Filter;
}

interface EntityList {
  list: EntityItem[];
  page: Page;
}

interface LatestUpdate extends ResponseProps {
  data: EntityList
}
```

#### ✅ 즐겨찾는 entity

##### path
- /entity/favorite
##### method
- GET
##### request
- page
- size
##### response
```typescript=
interface FavoriteItem {
  id: number;
  name: string;
  description: string;
  favoriteList: EntityItem[];
  publishedAt: string;
  filter: Filter;
}

interface FavoriteList {
  list: FavoriteItem[]; 
  page: Page;
}

interface Favorite extends ResponseProps {
  data: FavoriteList;
}
```

#### ✅ entity 즐겨찾기 추가

##### path
- /entity/favorite
##### method
- POST
##### request
- title
- description
- list (optional) - entity list
- serviceId
- graphId
- typeId
- propertyId
- keyword
##### response
```typescript
interface FavoriteResponseProps extends ResponseProps {
  data: boolean;
}
```

#### ✅ entity 즐겨찾기 수정

##### path
- /entity/favorite
##### method
- PUT
##### request
- title
- description
##### response
```typescript
interface FavoriteResponseProps extends ResponseProps {
  data: boolean;
}
```

#### ✅ entity 즐겨찾기 삭제

##### path
- /entity/favorite
##### method
- DELETE
##### request
- favoriteId
##### response
```typescript
interface FavoriteResponseProps extends ResponseProps {
  data: boolean;
}
```

#### ✅ entity 결과 항목 조회

##### path
- entity/list
##### method
- GET
##### request
- serviceId
- graphId
- typeId
- propertyId
- keyword
- page
- size
- entityId (optional)
##### response
```typescript
interface List extends ResponseProps {
  data: EntityList
}
```

#### ✅ entity 상세 정보 조회

##### path
- entity/detail
##### method
- GET
##### request
- entityId
##### response
```typescript
interface Detail extends ResponseProps {
  data: {} // 협의
}
```

### Query

#### ✅ 즐겨찾는 query

##### path
- /query/favorite
##### method
- GET
##### request
- page
- size
##### response
```typescript
interface QueryItem {
  id: number;
  name: string;
  publishedAt: string;
  count: number;
  query: string;
}

interface FavoriteItem {
  id: number;
  name: string;
  description: string;
  favoriteList: QueryItem[];
  publishedAt: string;  
  query: string;
}

interface FavoriteList {
  list: FavoriteItem[]; 
  page: Page;
}

interface Favorite extends ResponseProps {
  data: FavoriteList;
}
```

#### ✅ query 즐겨찾기 추가

##### path
- /query/favorite
##### method
- POST
##### request
- title
- description
- list (optional) - query list
- query
##### response
```typescript
interface AddFavorite extends ResponseProps {
  data: boolean;
}
```

#### ✅ query 즐겨찾기 수정

##### path
- /query/favorite
##### method
- PUT
##### request
- title
- description
##### response
```typescript
interface FavoriteResponseProps extends ResponseProps {
  data: boolean;
}
```

#### ✅ query 즐겨찾기 삭제

##### path
- /query/favorite
##### method
- DELETE
##### request
- favoriteId
##### response
```typescript
interface FavoriteResponseProps extends ResponseProps {
  data: boolean;
}
```

#### ✅ query 결과 항목 조회

##### path
- query/list
##### method
- GET
##### request
- query
- page
- size
##### response
```typescript
interface QueryList {
  list: QueryItem[];
  page: Page;
}

interface List extends ResponseProps {
  data: QueryList
}
```

#### ✅ query 상세 정보 조회

##### path
- query/detail
##### method
- GET
##### request
- queryId
##### response
```typescript
interface Detail extends ResponseProps {
  data: {} // 협의
}
```

#### ✅ ExampleQueryList
> 예제 쿼리 목록
##### path
- /query/example
##### method
- GET 
##### request
##### response
```typescript
interface ExampleQuery {
  id: number;
  name: string;
  query: string;
}

interface ExampleQueryList extends ResponseProps {
  data: ExampleQuery[];
}
```

---

## Model


### Filter

> 결과 필터 모델

```typescript
interface Data {
  id: number;
  name: string;
}

interface Filter {
  service: Data;
  graph: Data;
  type: Data;
  property: Data;
  searchString?: string;
  queryString?: string;
}
```


### Page

> 페이지 모델

```typescript
interface Page {
  totalPages: number;
  page: number; // current page index
  size: number; // rows per page
}
```


---
## To do
- 스컬리에게 기획 문의
    - (쿼리 조회 페이지의 리스트 클릭하면 팝업으로 나와야 하는지) 확인해보기
    - (p.5) `날짜, 조직도 > KakaoworkOrganization 외 1 AI 검색파트 4139 results` 뭔지..
    - 필터 마지막 부분의 entity가 type, property 중 property에 의존성이 있는지?
    - template API(p. 18-19)는 아직 안 나왔음
- API 협의 필요한 부분
    - EntityResultList(다 optional)
    - (p.26) 예제쿼리 
        - type 정보 같은 걸 물고 다니는 건가.. 
        - 지금 작성한 문서대로라면 한 번에 셀렉트박스 아이템들과 그와 매칭되는 쿼리 리스트를 다 받아옴


---




# 20201217 허블 스키마 재정의 피드백

## 추가해야 할 부분 
- 🚨 wiki에 즐겨찾기 추가 (POST) 추가해야 함
    - 쿼리 즐겨찾기 추가
    - 엔티티 즐겨찾기 추가
- favoriteItem에 필터 조건, 쿼리 조건 추가
- wiki EntityResultList에 추가해야 할 부분
    - request에 Paging 정보 -> size(rowsPerPage), page(currentPage)
    - typeId, propertyId를 오브젝트로 묶고 배열로 만들어야 한다.
    - entity/query 두 개로 쪼개기


## 수정해야 할 부분
- (p.26) 예제 쿼리 modal -> 예제 쿼리가 아직 없기 때문에 고려하지 않아도 됨.
- (p.27) 쿼리 모달 필요없음 -> 제거
- EntityResultList에 entityId, favoriteId를 없애고 entityId를 배열로 날리기
- 그냥 최근검색을 없애고 즐겨찾는 entity를 10개로 보여주는 걸로.
- (p.7) type명은 같고 property가 다를 경우 동일한 이름으로 쌓이는 이슈 -> property명까지 노출

## 스컬리 초대한 뒤 들은 이야기

- (p.7) 우리가 entity group이라고 생각했던 item들은 개별 엔티티가 맞다.
    - 눌렀을 때 딱 하나의 entity만 노출되면 된다.
    - 딱 하나만 뜨게 하려면 entity Id가 있어야..(hidden으로 entityId가 있어서 그게 들어오면 한 개만 뿌리는 식)
- (p.15) 즐겨찾기 추가를 일단 구현해야 하고 삭제, 수정은 시간이 되면 하면 좋다고 함(scully)


## 17시 30분 회의(honest, j, sion, edward, sam)

- (p.12) 즐겨찾기 버튼 통해 진입한 결과 화면 
    - honest가 이해한 것
        - 전체 리스트를 보여주고 즐겨찾기 아이템만 check박스 check해놓기
        - 즐겨찾기한 entity id까지 저장
        - 저장되는 정보 = **리스트 정보**와 **체크된 엔티티 리스트**
        - 리스트 뿌릴 때 아이디가 똑같으면 체크
    - sion의 의문
        - 첫 번째 페이지 1개, 마지막 페이지 1개 체크했다면..? 즐겨찾기의 의미가 퇴색되지 않나?
- (wiki) EntityResultList
    - **entity1, operator, entity2 합쳐서 string으로 보낼지 아니면 각각 보낼지 백엔드와 협의 필요**
- (p.21) 쿼리 조회 페이지에서 좌상단 서비스, 그래프 선택 셀렉트박스 필요한가?
    - 쿼리 자체가 필터 대신에 있는 거라서 중복으로 셀박이 있을 필요가 있을지..
    - 셀박 value 바꾼다고 페이지가 이동되어 버리면 저기 있을 필요가..?
    - 쿼리 페이지에서는 disable?

- 🚨 Result도 QueryResult, EntityResult 나누어야 함.
    - 사실 똑같은데 query가 있냐 없냐이기 때문에 생각해봄직함
    - API도 response는 동일하지만 request body가 다르기 때문에 나누는 게 맞다.
- 🚨 즐겨찾는 쿼리, 즐겨찾는 엔티티(p.7)도 분리해야 한다.
    - 필터를 들고 갈 수도 있고, 쿼리를 가지고 갈 수도 있고

- query 즐겨찾기 이야기 마무리되지 않음.
    - sion
        - main에서 리스트를 들고 있으면 되긴 함.
        - **체크박스된 애들 id 정보를 store에 넣어 두면** 됨.
    - honest
        - 검색 눌렀을 때, 리스트는 똑같으니까 entity list를 어떻게 노출시키느냐인데,
        - 새로고침 하면 스토어는 날아감 -> parameter로 물고 다녀야 하나..(더 안전하다고 생각)
    - j 
        - 즐겨찾는 쿼리에서 쿼리를 받고, 입력창에 query를 넣고 trigger를 건다. 
        - query로 조회했을 때는 url로 상태를 보정하지 않는다.
    - query 즐겨찾기는 어떻게 이동시킬 건가  
        - query는 물고 가는 게 아니라, store에 저장해도 되고, query response를 한 번 더 받아도 되고.
    - harmony에 service가 이미 response로 내려 오고 있음
        - graphId도 내려 달라고 요청해야


## 서버 이야기

- format이 바뀌니까 컴포넌트도 다 바뀜
- 이걸 메인에 올려버리면... msw를 안 바라보게 되니까 사이트가 죽을 것.
- msw용으로 따로 하나 있어야 하지 않을까?
- honest 
    - 일단 msw로만 작업을 하고.. swagger가 나오게 되면, cbt 추가하는 걸로.
- sion 
    - 그냥 main으로 머지하겠음.


## 템플릿 이야기
- 지라, 아지트 포함 5개 + 공통 1개 template scully가 작성해줄 예정
- @j.s가 template mapping하는 부분 담당해주실 것.
- [cruise.kakao.com/](http://cruise.kakao.com/) 참고 하면 클래스 구조 나와있음.