7. API 설계

 

서비스 구현에 사용될 OPEN API

• 공공데이터 포털
  1. 경기도_버스노선 조회
  2. 경기도_버스도착정보 조회
  3. 서울특별시_노선정보조회 서비스
  4. 서울특별시_버스도착정보조회 서비스
• 서울 열린데이터 광장
  1. 서울시 지하철역 정보 검색 (역명)
  2. 서울시 역코드로 지하철역별 열차 시간표 정보 검색

DB 설계

엔티티 관계 정의

user(1) : bm_group(n)

• 유저는 여러개의 BM그룹을 소유할 수 있다.

bm_group(1) : bmgroup_bookmark_map(n)

• bmgroup_bookmark_map는 n : n 테이블이다
• BM그룹은 여러개의 북마커를 가질 수 있다.

book_mark(1) : bmgroup_bookmark_map(n)

• bmgroup_bookmark_map는 n : n 테이블이다
• 북마커는 여러개의 BM그룹에 속할 수 있다.

metro(1) : metro_station(n)

• 지하철 노선은 여러 역을 소유한다.

metro_station(1) : metro_timetable(n)

• 역은 여러 시간표를 소유한다.

REST API

Auth API

• POST /api/auth/signup
  • 회원가입을 요청한다.
• POST /api/auth/signin
  • 로그인(토큰 발급)을 요청한다.
• GET /api/auth/me
  • 엑세스토큰 확인을 요청한다.
• GET /api/auth/refresh
  • 엑세스토큰 재발급 요청한다.
• GET /api/auth/signout
  • 로그아웃(토큰 블랙리스트 등록)을 요청한다.

Bus API

• GET /api/buses?routeName=:routeName
  • 버스 번호와 일치하는 버스 목록을 조회한다.
• GET /api/buses/arrival?type=:type
  • 버스의 도착정보를 조회한다.
  • 필수 쿼리: stationId=:stationId&routeId=:routeId&stationSeq=:stationSeq
• GET /api/buses/:routeId?type=:type
  • 특정 버스의 상세정보 조회한다.
• GET /api/buses/:routeId/stations?type=:type
  • 특정 버스의 경유 정류소 목록을 조회한다.

Metro API

• GET /api/metros
  • 지하철 노선 목록을 조회한다.
• GET /api/metros?stationName=:stationName
  • 역이름과 일치하는 역을 가진 모든 부모 노선을 조회한다.
  • include=stations : 옵션 사용시 응답에 자식 자원인 '역 목록'을 포함한다.
• GET /api/metros/:metroId/stations
  • 특정 노선의 역 목록을 조회한다.
• GET /api/metros/:metroId/stations/:stationId/arrival?inOutTag=:inOutTag
  • 특정 노선 특정역의 도착시간을 조회한다.

Station API

• GET /api/stations?stationName=:stationName
  • 정류소 이름과 일치하는 정류소 목록을 조회한다.
• GET /api/stations/:stationId/buses?type=:type
  • 특정 정류소에 정차하는 버스 목록을 조회한다.

Bm Groups API

(모든 요청 쿠키에 엑세스토큰 필요.)

• GET /api/bm-groups
  • 사용자의 bm 그룹 목록을 조회한다.
  • include=book-marks : 옵션 사용시 응답에 자식 자원인 '북마크 목록'을 포함한다.
  • q=routeId=:routeId,stationSeq=:stationSeq,stationId=:stationId : 검색 옵션 사용시 일치하는 자원을 가져온다.
• POST /api/bm-groups
  • 사용자의 bm 그룹을 신규 추가한다.
• DELETE /api/bm-groups/:bmGroupId
  • 사용자의 특정 bm 그룹을 삭제한다.

Book Mark API

(모든 요청 쿠키에 엑세스토큰 필요.)

• GET /api/bm-groups/:bmGroupId/bookmakes
  • 사용자의 특정 bm 그룹의 북마크 목록을 조회한다.
  • q=routeId=:routeId,stationSeq=:stationSeq,stationId=:stationId : 검색 옵션 사용시 일치하는 자원을 가져온다.
• POST /api/bm-groups/:bmGroupId/book-marks
  • 사용자의 특정 bm 그룹에 신규 북마크를 등록한다.
• DELETE /api/bm-groups/:bmGroupId/book-marks/:bookMarkId
  • 사용자의 특정 bm 그룹에 특정 북마크를 삭제한다.

지하철 노선 데이터 파이프라인

버스 API 같은 경우 '공공데이터 포털'과, '서울 열린데이터 광장'에서 제공하는 Open API를 내부적으로 호출하는 방식으로 구현하였다.

지하철 API의 경우 지하철 도착정보는 실시간으로 제공 되는 API를 찾을 수 없었다.
때문에 노선 정보(metro), 역 리스트(metro_station), 역별 도착시간표(metro_timetable)를
따로 DB에 저장하여 제공하는 방식을 선택했다.

지하철 데이터를 DB에 저장하는 과정

1. 노선이 가진 역의 순서를 찾는다.

역의 순서를 찾는게 생각보다 쉽지 않았는데 이유는 이러하였다.
버스는 노선을 순환이 기본인 반면 지하철은 기점과 종점이 분명한 노선도 있고, 아닌 노선이 있었기 때문이다.

대표적으로 1호선의 경우가 정말 난해 했다.
임의로 기점과 종점을 정의 해도 됐지만 이왕이면 조금 더 정확한 방법을 사용하고 싶었다.
결론적으로 찾은 방법은 '서울메트로'의 지하철 정보 웹페이지의 script을 내려 받는 방법으로 순서를 찾았다.

• http://www.seoulmetro.co.kr/kr/getLineData.do

/**
* 서울 교통공사 웹 사이트의 데이터를 사용하여 ts 파일 생성
* - 이 데이터를 통해 열차 순서 정보를 알 수 있다.
*/
async function createSeoulMetroDataFile(fileName: string): Promise<void> {
    const url = 'http://www.seoulmetro.co.kr/kr/getLineData.do';
    try {
        let data = await api.callApi(url, false);
        data = data.replace('var lines', 'export const seoulMetroData: any');
        data = data.replace(/"sub-nm": "",/gi, '');
        await promises.writeFile(join(__dirname, fileName), data);
    } catch (error) {
        console.error('서울 교통공사 js 데이터를 가져오는데 실패 했습니다.');
        throw error;
    }
}

2. 노선과 역 리스트 정보를 구한다.

노선 리스트 insert DB

• 위의 '1. 노선이 가진 역의 순서를 찾는다.'에서 구한 파일을 파싱하여 노선 리스트를 구하여 DB에 저장한다.

노선의 역 리스트 insert DB

• 서울시 열린데이터 광장의 '서울시 지하철역 정보 검색 (역명)' OPEN API를 사용하여 구한다.
• 단점은 해당 API는 서울시에서 제공하기 때문에 모든 역의 정보를 제공하지는 않는다.

3. 역별 시간표를 구한다.

• 역별 시간표는 서울시 열린데이터 광장의 '서울시 역코드로 지하철역별 열차 시간표 정보 검색' OPEN API를 사용하여 구한다.
• 시간표의 경우 역별 x 평일, 토요일, 휴일/일요일 x 상행(내선), 하행(외선)이 된다
• 시간표 총개를 확인하기 위한 SQL
• SELECT m.metro_name , count(*) FROM metro m JOIN metro_station ms ON ms.metro_id = m.id JOIN metro_timetable mt ON mt.metro_station_id = ms.id GROUP BY m.metro_name;
• 결과 확인