RESTful API

REST API란?

어떤 자원에 대해 CRUD를 진행할 수 있게 HTTP Method(GET, POST, PUT, DELETE)를 사용하여 요청을 보내는 것. 이 때, 요청을 위한 자원은 특정한 형태로 표현된다.

URI를 통해 정보의 자원을(only 자원만을) 표현하고, 자원의 행위는 HTTP Method로 명시한다.

• 자원(Resource) : URI
• 행위(Verb) : HTTP Method
• 표현(Representations)

 

디자인 가이드

1. URL은 정보의 자원을 표현해야 함
   리소스명은 동사보다 명사를 사용. delete와 같은 행위에 대한 표현이 들어가면 안됨
2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현
   예) 정보를 가져올 땐 GET, 추가할 땐 POST ...
   - POST : 생성
   - GET : 조회하고 가져오기
   - PUT : 수정
   - DELETE : 삭제

 

주의사항

• 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용하고, 마지막 문자로 슬래시(/)를 포함하지 않는다.
  /house/apartments
  /animals/mammals/whales
• 하이픈(-)은 URL 가독성을 높이는데 사용. 밑줄(_)은 가독성 문제로 URL에 사용하지 않는다.
  불가피하게 긴 URL경로를 사용하게 된다면 쉽게 읽고 해석하기위해 하이픈 사용해서 가독성을 높일 수 있음
• 소문자 적합
• 확장자 포함시키지 않는다

 

리소스 간의 관계 표현하는 방법

/리소스명/리소스 ID/관계가 있는 다른 리소스명

GET : /users/{userid}/devices     --- 일반적으로 소유(has)의 관계를 표현할 때

 

관계명이 애매하거나 구체적인 표현이 필요하면 명시적으로 표현할 수 있음

GET : /users/{userid}/likes/devices     --- 사용자가 ‘좋아하는’ 디바이스 목록

 

자원을 표현

컬렉션은 문서들의 집합, 객체들의 집합. 컬렉션은 복수형(-s)으로 사용

도큐먼트는 문서, 한 객체

/sports/soccer     --- sports라는 컬렉션과 그 중  soccer라는 도큐먼트로 생각됨

/sports/soccer/13     --- sports, players라는 컬렉션과 soccer, 13을 의미하는 도큐먼트

 

 

 

 

---

Path Variable

/users/10

• 이름에서도 유추할 수 있듯, 경로 자체에 변수(10)를 사용한 방법입니다.
• 전체 데이터 또는 특정 하나의 데이터를 다룰 때 처럼, 리소스를 식별하기 위해 사용돼요.

 

Query Parameter

/users?user_id=10

데이터를 정렬하거나 필터링 하는 경우 더 적합합니다.

 

 

 

---

Reference

https://meetup.nhncloud.com/posts/92

REST API 제대로 알고 사용하기 : NHN Cloud Meetup