REST API

 

 

REST : Representational State Transfer의 약자이다.

• REST API는 URI를 통해서 자원을 나타낸다.
• HTTP Method를 이용하여 자원의 행위를 규정한다.

HTTP Method는 GET, POST, PUT, DELETE가 대표적이다.
GET: 조회
POST: 등록
PUT: 수정
DELETE: 삭제

여기서 말하는 자원이란?

RESTful한 URI에서 가르키는 자원은 객체를 뜻하는 것이다.

해당 자원(resource)은 네 가지로 나눌 수 있다.

리소스가 아래 네 가지중 어느 범주에 해당되는 지 확인하고, 그에 맞는 URI를 생성해 나가야 한다.

 

• Document
  • Document는 1개의 개체를 나타내는 것이며, 인스턴스와 유사한 개념이다. - 단수형 표현
  • REST에서는 리소스 집합(Collection)중 하나로 나타나며, 일반적으로 collection뒤에 /로 구분지어 나타낸다.
  • 아래 예제에서는 위에서부터 {device-id}, {id}, admin가 document 리소스라고 볼 수 있다.

http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin

 

 

• Collection
  • Collection은 Document(단일 리소스) 들의 묶음이다. - 복수형 표현
  • 아래 예제에서는 위에서부터 managed-devices, users, accounts라고 볼 수 있다.
  • 주로 post기반이다.

http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts

 

 

• Store
  • 새로운 URI를 생성하지 않는다. - 복수형 표현
  • client가 관리한 형태를 띈다.
  • 주로 put을 기반으로 등록한다.

http://api.example.com/song-management/users/{id}/playlists
http://api.example.com/management/users/{id}/accounts

 

 

• Controller
  • document, collection, store로 해결하기 어려운 프로세스 실행
  • 동사를 직접 사용한다. (cotroller의 경우 리소스를 조작하는게 아닌 직접 function을 실행하는 행위를 나타내기 위해 사용하므로 동사를 사용해도 무방하다.)

http://api.example.com/song-management/users/{id}/playlist/play

 

 

REST API 규칙

1. 동사가 아닌 명사로 리소스를 표현한다.
   - 명사는 해당 리소스의 속성을 표현할 수 있기 때문이다.
2. 소문자 사용
   - 주소에서는 대소문자를 구분하므로, 카멜방식이 아닌 소문자를 사용하여 작성한다.
3. 단어를 이어줄때는 하이픈을 사용한다.
   - 가급적이면 명사하나로만 표현하되, 불가피한 경우 하이픈 사용.
4. 슬래시(/)는 계층을 구분하는 용도로, 마지막에 슬래시는 포함하지 않는다.
5. URI에 CRUD 함수를 사용하지 않는다..
   - URI는 어떤 동작이 수행 되는지 가르키는게 아니라, 리소스를 가르키는 것이다.
   리소스에 대한 작업(행위)은 HTTP Method를 사용하여 요청한다.

// Bad
POST http://restapi.example.com/users/1/delete-post/1

// Good
DELETE http://restapi.example.com/users/1/posts/1

   6. 파일 확장자는 URI에 포함시키지 않는다.

   7. 컨트롤 리소스를 제외하고는 명사를 사용한다.

   8. 필터 URI의 경우에는 신규 API를 생성하지 않고, 쿼리 파라미터를 활용한다.

 

 

 

 

출처 : https://restfulapi.net/resource-naming