API_README.md

API 문서 작성 가이드

파일 구조 설명

api.py              API 서버 Flask app
api/
    __init__.py     API를 등록(register)하는 함수가 작성되어 있다.
    model.py        API로 모델링될 DB 모델의 base class (docstring exists)
    view.py         각 모델에 대해 생성될 view의 base class (docstring exists)
    v0_1/
        __init__.py API v0.1 구성 및 등록
                    어떤 URL에 어떤 리소스가 바인딩되어 있는지 알 수 있다.
        party.py    API v0.1의 /party 리소스에 대한 view
        person.py   "
        bill.py     "

API 문서 쓰는 법

1. party, person, bill의 세 가지 리소스 타입에 대해 다음 세 가지 URL을 접속해 보고, 각각 어떤 형식으로, 어떤 반환값들이 제공되는지 확인한다.
   • /v0.1/bill/: 리스트 (_type: 'list')
     예) http://api.pokr.kr/v0.1/bill/
   • /v0.1/bill/search: 검색 (_type: 'search')
     예) http://api.pokr.kr/v0.1/bill/search
   • /v0.1/bill/<id>: 단일 엔티티 (_type: 'single')
     예) http://pokr.kr/api/v0.1/bill/1906357
2. URL에 패러미터들을 하나씩 넣어보며 어떤 효과가 있는지 확인한다.
3. (선택) api/model.py, api/view.py, models/(party|person|bill).py를 읽어보며, 어떤 식으로 동작하는지 확인한다.
   • models/(party|person|bill).py에서는 _to_dict_light() 함수를 보면 된다.
   • api/model.py는 class docstring 정도만 보면 충분하다.
   • api/view.py가 핵심인데 조금 어렵다. 자세한 구현 방식이 궁금하다면 api/__init__.py와 Method Based Dispatching 와 함께 보면 이해가 될...지도 안 될지도ㅋㅋ

Parameters

Common

• projection: light(default), full의 값을 가지며, full이 선택되면 각 아이템에 대해 더 상세한 정보를 반환한다.

List/Search

• sort: 정렬 기준 column 이름
• order: asc / desc(default)
• page: 페이지 넘버 (default: 1)
• per_page: 한 페이지(request)당 반환될 아이템 수 (default: 20)

Search

• q: 검색어