jabsiri......
REST API 디자인 가이드
lahuman
2016. 3. 15. 14:34
REST API 디자인 가이드
- 심플하고 직관적으로 만들자
+ 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 정보를 삭제 |
- 리소스간의 관계를 표한하는 방법
- 서브 리소스로 표현하는 방법
+ /”리소스명”/”리소스 id”/”관계가 있는 다른 리소스명” 형태
+ HTTP Get : /users/{userid}/devices
예) /users/terry/devices
- 서브 리소스에 관계를 명시하는 방법
+ HTTP Get : /users/{userid}/likes/devices
예) /users/terry/likes/devices
- 에러처리
- 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"}
- API 버젼관리
- Facebook?v=2.0
- salesforce.com /services/data/v20.0/sobjects/Account
- {servicename}/{version}/{REST URL}
예) api.server.com/account/v2.0/groups
- 페이징
- 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개의 레코드를 출력한다.
- Partial Response 처리
특정 플드만 전달하는 경우 사용
- Linked in : /people:(id,first-name,last-name,industry)
- Facebook : /terry/friends?fields=id,name
- Google : ?fields=title,media:group(media:thumnail)
- 검색
일반적으로 Query String 만 사용하게 되면 페이징 조건과 분간이 안감
- 예시
+ /users?name=cho®ion=seoul&offset=20&limit=10
- 추천 방안
+ /user?q=name%3Dcho,region%3Dseoul&offset=20&limit=10
출처 : 조대협의 블로그
MD 파일 :
REST_API디자인_가이드.md
REST_API디자인_가이드.md