REST API 설계하기

REST API 란 ? )

REST를 기반으로 만들어진 API

 

그럼 REST란? )

Representational State Transfer 의 약자로

자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것.

  1. HTTP URI를 통해 자원 명시

  2. HTTP Method(GET, POST, PUT, PATCH, DELETE)를 통해

      해당 자원에 대한 CRUD Operation을 적용하는 것. 

 

REST 구성요소

1. 자원 : HTTP URI

2. 행위 : HTTP Method

3. 표현

 

REST API 설계 시 중요한 항목 

1. URI는 정보의 자원을 표현해야 한다.

2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, PATCH, DELETE)로 표현한다.

 

 

설계 규칙

1. 소문자를 사용한다.

카멜 방식이 아닌 소문자를 이용하여 작성한다.

❌ http://restapi.example.com/members/signUp
⭕ http://restapi.example.com/members/signup

 

 

2. 언더바 대신 하이픈 사용

가급적 하이픈도 최소화하고 정확한 의미나 표현을 위해 단어의 결합이 불가피한 경우 사용

❌ http://restapi.example.com/members/sign_up
⭕ http://restapi.example.com/members/sign-up

 

 

3. 마지막에 슬래시를 포함하지 않는다.

슬래시는 계층을 구분하는 것으로 마지막에는 사용하지 않는다.

❌ http://restapi.example.com/members/
⭕ http://restapi.example.com/members

 

 

4. 행위는 포함하지 않는다.

행위는 URL 대신 Method를 사용하여 전달한다. (GET, POST, PUT, DELETE 등)

❌ POST http://restapi.example.com/members/1/get-info
⭕ GET http://restapi.example.com/members/1

 

 

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

REST API에서는 메세지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI안에 포함시키지않는다. 

Accept header를 사용한다. 

❌ http://restapi.example.com/members/image.jpg
⭕ http://restapi.example.com/members/image
      HTTP/1.1 Host: restapi.example.com Accept: image/jpg

 

 

6. 자원에는 명사를 사용한다.

가급적 전달하고자 하는 자원의 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 허용한다.

❌ http://restapi.example.com/posts/duplicating
⭕ http://restapi.example.com/posts/duplicate

 

 

+ 

1.로그인 한 사용자 정보를 조회할 때 /members/{id} 로 해도 되지만 컨트롤러의 메소드에서 @AuthenticationPrincipal을 사용하면 URI에 id 를 받지 않아도 된다.

2.  API 리소스를 복수형으로 설계하면 리소스의 컬렉션을 나타낸다. 예를 들어 /members는 member의 컬렉션을 나타내어 이 컬렉션에 대해 다양한 CRUD 작업을 할 수 있음을 암시한다.

3. PUT vs PATCH
PUT은 자원 전체를 수정할 때, PATCH는 일부만 수정할 때 사용한다.
PUT : 클라이언트가 서버상의 자원 전체를 업데이트.
자원이 존재하지 않으면 새 자원생성.
자원의 전체 표현을 포함해야한다.
자원의 모든 필드를 클라이언트가 보낸 값으로 대체.
일반적으로 PUT요청은 URI에 직접 매핑 ( PUT /members/123)

PATCH : 자원의 일부 업데이트
자원이 존재하지 않으면 일반적으로 실패.
서버는 보낸 필드만 업데이트하고, 나머지는 변경하지 않음.

---

참고

https://devuna.tistory.com/79

[REST API] URL 규칙, RESTful한 URL이란?

https://velog.io/@bruce1115/5.-API-%EC%84%A4%EA%B3%84%ED%95%98%EA%B8%B02-Endpoint-%EC%9E%91%EC%84%B1

5. API 설계하기(2) - Endpoint 작성

개발 초보를 위한 RESTful API 설계 가이드 (velog.io)

개발 초보를 위한 RESTful API 설계 가이드