REST API 디자인 가이드

REST API 디자인 가이드

1. 심플하고 직관적으로 만들자

    + 2 depth 정도로 간단하게 만드는 것이 이해하기 편함
      - /docs
      - /docs/123
    + 동사 보다는 명사를 사용
      - 단수형 명사(/dog) 보다 복수형 명사(/dogs)를 사용하는 것이 의미상 좋음
    + 사용 예
   

   리소스	POST	GET	PUT	DELETE
   	create	read	update	delete
   /dogs	새로운 dogs 등록	dogs 목록을 리턴	Bulk로 여러 dogs 정보를 업데이트	모든 dogs 정보를 삭제
   /dogs/baduk	에러	baduk 이라는 이름의 dogs 정보를 리턴	baduk이라는 이름의 dogs 정보를 업데이트	baduk 이라는 이름의 dogs 정보를 삭제

2. 리소스간의 관계를 표한하는 방법

      - 서브 리소스로 표현하는 방법
        + /”리소스명”/”리소스 id”/”관계가 있는 다른 리소스명” 형태
        + HTTP Get : /users/{userid}/devices
        예) /users/terry/devices
      - 서브 리소스에 관계를 명시하는 방법
        + HTTP Get : /users/{userid}/likes/devices
        예) /users/terry/likes/devices
   

3. 에러처리

        - 200 성공
        - 400 Bad Request - field validation 실패시
        - 401 Unauthorized - API 인증,인가 실패
        - 404 Not found - 해당 리소스가 없음
        - 500 Internal Server Error - 서버 에러
        - 예시
          + HTTP Status Code : 401
          {“status”:”401”,”message”:”Authenticate”,”code”:200003,”more info”:”http://www.twillo.com/docs/errors/20003"}
   

4. API 버젼관리

        - Facebook?v=2.0
        - salesforce.com /services/data/v20.0/sobjects/Account
        - {servicename}/{version}/{REST URL}
        예) api.server.com/account/v2.0/groups
   

5. 페이징

        - Facebook API 스타일 : /record?offset=100&limit=25
        - Twitter API 스타일 : /record?page=5&rpp=25 (RPP는 Record per page로 페이지당 레코드수로 RPP=25이면 페이지 5는 100~125 레코드가 된다.)
        - LikedIn API 스타일 : /record?start=50&count=25
        - 구현 관점에서 보면 , 페이스북 API가 조금 더 직관적이기 때문에, 페이스북 스타일을 사용하는 것을 권장한다.
      예) record?offset=100&limit=25 : 100번째 레코드에서부터 25개의 레코드를 출력한다.
   

6. Partial Response 처리

        특정 플드만 전달하는 경우 사용
        - Linked in : /people:(id,first-name,last-name,industry)
        - Facebook : /terry/friends?fields=id,name
        - Google : ?fields=title,media:group(media:thumnail)
   

7. 검색

    일반적으로 Query String 만 사용하게 되면 페이징 조건과 분간이 안감
     - 예시
       + /users?name=cho&region=seoul&offset=20&limit=10
     - 추천 방안
       + /user?q=name%3Dcho,region%3Dseoul&offset=20&limit=10
   

출처 : 조대협의 블로그

MD 파일 : 

REST_API디자인_가이드.md