Untertaxi API

설치, 테스트, 실행

로컬에서 실행하려면 필요한것.

1. Python 3.6+
2. Postgres 10+

Docker을 이용하여 실행하기 위해 필요한것.

1. docker-compose 1.21+
2. docker 18+

Docker-Compose 실행

1. cd docker-compose/
2. docker-compose up
3. http://localhost:5000 에 서버 시작되었음.

Virtualenv(venv)을 설정하여 로컬 실행환경 만들기

1. virtualenv -p python3 venv :: venv 생성.
2. source venv/bin/activate :: venv 활성화.
3. pip install -r requirements.txt :: 의존성 모듈들 venv내에 설치.

로컬에서 테스트 실행

1. py.test :: 테스트 실행.
   • 테스트 실행시 SQLite3 inmem DB 사용하여 별도의 데이터베이스 불필요.

로컬에서 서버 실행

1. DB :: 127.0.0.1:5432 에 Postgres 실행되고 있어야함.
   1. 사용자명/패스워드는 postgres / postgres.
   2. untertaxi_api database생성 :: CREATE DATABASE untertaxi_api
2. 데이터베이스 마이그레이션 실행.
   1. ./manage.py db upgrade
   2. 최초 한번 데이터베이스 초기화를 위해 필요하고, 이후에 서버 실행시는 불필요.
3. 서버 실행.
   1. ./manage.py runserver

API 문서

로그인 방식

1. HTTP Basic Authentication 을 사용.
   • 다만, password 을 서버의 SECRET_KEY 을 이용하여 SHA-256 해시하여 전송.
2. 참고 예제 :: https://github.com/ageldama/untertaxi-api-flask/blob/master/misc/new-user-and-ride-request.py#L30
3. 이하 로그인이 필요한 API은 항상 별도로 표시하지않고,
   1. 로그인이 불필요한 경우에만 표기한다.
   2. 로그인 실패시 HTTP응답 코드로 401 UNAUTHORIZED 이며, 로그인 필요한 API에서 반복적으로 언급하지 않겠다.

회원 (승객, 기사)

• **회원** 리소스는 MemberType enum에 따라서 승객과 기사로 구분.
  1. 승객 :: PASSENGER
  2. 기사 :: DRIVER

회원 가입 PUT /v1/member

1. 요청
   1. 로그인 불필요.
   2. JSON Request Body

{
  "email":  "[email protected]",  // 문자열, 필수.
  "password": "mypass",     // 문자열, 필수. 평문 비밀번호.
  "member_type": "DRIVER"
}

1. 응답
   1. 201 CREATED :: 성공. 응답본문없음.
   2. 400 BAD REQUEST :: 실패. 응답본문없음.

1. 잘못된 이메일 양식.
2. 혹은 이미 가입된 이메일 주소.
3. 비밀번호가 4글자 이하.
4. 잘못된 회원타입(MemberType).

회원 정보 GET /v1/member/<member_id>

1. 다른 배차요청 목록 과 같은 API으로 얻은 member_id 에 맞는 회원정보를 조회할때 사용.
2. 요청
   1. 요청 본문 없음.
   2. <member_id> path variable으로 정보를 얻고 싶은 회원 ID을 지정.
3. 응답
   1. 200 OK :: 성공.

1. JSON으로 다음과 같은 응답.

   {
       "email": "[email protected]", // 회원 이메일.
       "active": true,  // 삭제되지않은 회원인가.
       "created_at": "2018-05-18 12:33:12",  // 최초 생성일, 문자열.
       "update_at": "2018-05-18 12:33:12",  // 최종 수정일, 문자열.
   }
       

   1. 400 BAD REQUEST :: 실패

• 해당 member_id 의 회원이 없다.

주소

주소 목록 GET /address

1. 로그인한 사용자의 계정으로 등록한 배차 목적지 주소 목록.
   • 다른 사람이 등록한 주소지는 제외된다.
2. 응답
   1. 200 OK :: 응답JSON본문

[
    // 다음의 배열,
    {
        "id": 12345,  // 주소지id
        "member_id": 987,  // 이 주소지를 등록한 회원id
        "address": "이젠 여기",  // 주소지 문자열
        "created_at": "...",  // 최초 등록일시
        "updated_at": "...",  // 최종 수정일시
        "active": true  // 삭제여부
    }
]

주소 등록 PUT /v1/address

1. 새로운 배차 목적지를 등록한다.
   • 기존에 등록해놓은 목적지가 없을 경우에 사용.
2. 요청
   1. 요청본문 JSON

{
    "address": "아까 거기"  // 문자열, 100글자. 필수.
}

1. 응답
   1. 200 OK :: 성공.

1. JSON응답

   {
       "id": 1234 // 등록한 address의 id
   }
       

   1. 400 BAD REQUEST :: 실패
2. 응답본문없음.
3. 요청의 address 필드가 없거나,
4. 요청의 주소 문자열이 100글자 초과.

주소 정보 GET /v1/address/<address_id>

1. 지정한 주소지 id의 정보를 얻는다.
   • 내가 등록한 주소지가 아니어도, 배차요청등을 표시하기 위해 다른 사람의 주소지 정보도 얻을수있다.
2. 요청
   1. Path Variable으로 address_id 주소지 id 지정.
3. 응답
   1. 200 OK :: 응답JSON본문

{
    "id": 12345,  // 주소지id
    "member_id": 987,  // 이 주소지를 등록한 회원id
    "address": "이젠 여기",  // 주소지 문자열
    "created_at": "...",  // 최초 등록일시
    "updated_at": "...",  // 최종 수정일시
    "active": true  // 삭제여부
}

1. 400 BAD REQUEST :: 실패

• 지정한 address_id 의 주소지가 등록되어 있지 않다.

주소 삭제 DELETE /v1/address/<address_id>

1. 로그인한 회원이 등록한 배차요청 목적지 주소를 삭제한다.
2. 요청
   1. Path Variable으로 삭제할 address_id 을 지정.
3. 응답
   1. 204 NO CONTENT :: 성공적으로 삭제. 응답본문없음.
   2. 400 BAD REQUEST :: 해당 address_id 의 주소 없음.
   3. 401 UNAUTHORIZED :: 지정한 주소지가 요청한 사람의 회원과 같지 않아 삭제를 거부.

배차요청

배차요청의 상태

1. AVAILABLE :: 배차요청을 생성하였고, 배차가 가능한 상태.
2. ACCEPTED :: 배차 받은 상태.
   • AVAILABLE 상태의 배차요청만 ACCEPTED 할수있다.
3. ARRIVED :: 배차 받아 목적지에 도착.
   • ACCEPTED 상태의 배차요청만 ARRIVED 할수있다.
4. CANCELLED :: 취소한 배차요청.
   • 모든 상태의 배차요청은 취소될 수 있다.

배차요청 생성 PUT /v1/ride_request

1. 새로운 배차 요청을 생성한다.
   • 요청을 보내는 로그인 사용자을 승객으로 하여 생성,
   • 처음 생성시 status 은 자동적으로 AVAILABLE 으로 생성한다.
2. 요청
   • 요청본문JSON

{
    "address_id": 12345  // 배차요청할 목적지 주소id.
}

1. 응답
   1. 200 OK :: 생성완료, 요청본문JSON

{
    "id": 383  // 생성한 배차요청id.
}

1. 400 BAD REQUEST :: 실패, 지정한 address_id 을 찾을수없음.

배차요청 목록 GET /v1/ride_request

1. 모든 사용자의 모든 상태인 전체 배차요청 목록.
2. 응답
   1. 200 OK

[
    // 다음과 같은 배차요청 항목들의 배열,
    {
        "id": 123545,  // 배차요청id.
        "passenger_id": 123,  // 배차요청한 승객id.
        "driver_id":  null,  // 배차요청을 승인한 기사id. (승인대기중이면 null)
        "address_id": 1,  // 목적지 주소id.
        "created_at": "...",  // 최초 생성일시.
        "updated_at": "...",  // 최종 수정일시.
        "status": "AVAILABLE"  // 배차요청의 상태.
    },
    ...
]

배차요청 취소 DELETE /v1/ride_request/<ride_request_id>

1. 로그인한 사용자의 배차요청을 취소한다.
   • 다른 사용자의 배차요청은 취소할수없다.
2. 요청
   1. Path Variable ride_request_id 으로 취소하고 싶은 배차요청을 지정한다.
   2. 요청본문은 없다.
3. 응답
   1. 204 NO CONTENT :: 처리완료.
   2. 400 BAD REQUEST :: 해당 배차요청없음.
   3. 401 UNAUTHORIZED :: 해당 배차요청은 다른 사용자의 배차요청.

배차요청 승인 POST /v1/ride_request/<ride_request_id>/accept

1. 기사인 회원이 다른 회원이 생성한 배차요청을 승인한다.
   • 자신이 생성한 배차요청은 승인할 수 없다.
   • MemberType 이 DRIVER 인 회원만 승인할 수 있다.
2. 요청
   1. Path Variable ride_request_id 으로 승인할 배차요청을 지정.
   2. 요청본문은 없다.
3. 응답
   1. 204 NO CONTENT :: 승인완료.
   2. 400 BAD REQUEST :: 해당 배차요청이 없음.
   3. 401 UNAUTHORIZED :: API호출하는 사용자가 DRIVER 이 아니거나, 지정한 배차요청이 대기상태의(AVAILABLE) 요청이 아님.

배차요청 도착 POST /v1/ride_request/<ride_request_id>/arrive

1. 기사 자신이 승인했었던 배차요청을 목적지에 도착했을때, 완료로 처리.
   • 자신이 승인한 배차요청만 도착처리가 가능.
2. 요청
   1. Path Variable ride_request_id 으로 도착처리할 배차요청을 지정.
   2. 요청본문은 없다.
3. 응답
   1. 204 NO CONTENT :: 도착처리 완료.
   2. 400 BAD REQUEST

1. 해당 배차요청이 없거나,
2. 승인상태의 배차요청이 아님.
   1. 401 UNAUTHORIZED
3. API호출한 회원이 DRIVER 타입이 아님.
4. 내가 승인하여 처리한 배차요청이 아님.