초보 개발자들을 위한 REST API 정리

REST API가 뭔지도 몰랐던 몇 년 전 REST API라는 것을 보았을 때 생각해보면 이게 뭔가 싶었습니다.

REST라는 기술을 지원해주는 api가 있는가 싶기도 하고, 구글 검색으로 찾아보아도 그 당시엔 이해하기 너무 어려웠고, 많이 고민을 했었습니다.

지금에서야 REST에 대해서 조금?은 이해하게 되었고, 초보 개발자들에게 보다 쉽게 이해할 수 있도록 정리해보려고 합니다.

# REST란? 

잠깐 위키를 찾아보면, 

"Representational State Transfer REST(Representational State Transfer)는 월드 와이드 웹과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식이다. 이 용어는 로이 필딩(Roy Fielding)의 2000년 박사학위 논문에서 소개되었다. 필딩은 HTTP의 주요 저자 중 한 사람이다. 이 개념은 네트워킹 문화에 널리 퍼졌다."

뭐 이렇다네요. 우리에겐 이런것들은 아무 도움되지 않기 때문에 패스합니다.

 

쉽게 설명해서,

URL에 자원을 표현하는 방식으로 REST 규칙에 맞게 코딩을 추구하는 아키텍처입니다. URL만 봐도 한눈에 어떤 자원을 제공하는지 쉽게 알 수 있습니다.

/users/1

 

즉, REST API란 

REST 규칙에 맞는 URL의 기반으로 직접 서비스 API를 구현하는 것이고, REST 하게 짜인 서비스를 API로 공개하거나, 여러 플랫폼을 지원할 때 사용한다라고 생각하면 됩니다.

 

예로 들면, 

https://developers.naver.com/docs/login/api/

네이버아이디로로그인 개발가이드

네이버  OAuth 로그인 API를 사용할 때, 네이버 디벨로퍼에서 제공하는 API 요청 URL을 자세히 보면 REST 한 URL로 되어있는 것을 볼 수 있습니다.

정리하자면, 네이버에서 OAuth 로그인 REST API를 제공하는것을 우리가 사용하듯, 우리가 REST 하게 API를 구현하여 제공하는 것을 REST API라고 합니다.

 

메서드	인증	요청 URL	출력포멧	설명
GET / POST	OAuth 2.0	https://nid.naver.com/oauth2.0/authorize	URL 리다이렉트	네이버 아이디로 로그인 인증 요청
GET / POST	OAuth 2.0	https://nid.naver.com/oauth2.0/token	json	접근 토큰 발급/갱신/삭제 요청

# REST 규칙

사용자의 정보를 가져오고싶을 때 아래의 보기처럼 사용하면 REST 하지 않습니다.

/users/get/1/

/users?get=1

 

1. REST 기본 규칙

• URL은 정보의 자원을 표현해야 합니다.
• 자원의 행위는 HTTP Method(Get, Post, Put, Patch, Delete)으로 표현합니다.

2. REST 설계 규칙

• URL의 마지막에는 "/"를 포함하지 않습니다.
• URL의 자원은 동사보단 명사로 표현합니다.
• URL은 _ (언더바) 보다 - (하이픈)을 사용합니다.
• URL은 소문자를 사용합니다.

기본규칙과 설계규칙을 따라 작성하면 다음과 같습니다.

Method	URL(Resource)	action	description
GET	/users	list	유저들의 정보를 가져온다.
POST	/users	create	새로운 유저를 생성한다.
GET	/users/:id	show	해당(:id)하는 유저의 정보를 가져온다
PUT	/users/:id	update	해당(:id)하는 유저를 수정한다.
DELETE	/users/:id	quit	해당(:id)하는 유저를 삭제한다.

# HTTP Status Code 

URL을 RESTfull 하게 작성하는 것도 중요하지만 요청했을 시 반환하는 응답상태도 매우 중요합니다. HTTP 요청이 성공했는지, 실패했는지, 실패를 했으면 왜 실패했는지에 대한 코드입니다.

그렇기에 코드만 보더라도 대략적으로 어떠한 오류가 발생했고, 성공했는지를 알 수 있습니다.

 

code	action	description
200	OK	클라이언트의 요청을 서버가 정상적으로 처리함.
201	Created	클라이언트의 요청을 서버가 정상적으로 처리하였고, 새로운 리소스가 생김.
202	Accepted	클라이언트의 요청은 정상적으로 처리했으나, 서버가 아직 요청을 완료하지 못함.
400	Bad Request	클라이언트의 요청이 부적절 할 경우 사용하는 응답코드
401	Unauthorized	클라이언트가 권한이 없을때, 서버가 처리할 수 없는 경우
405	Method Not Allowed	클라이언트의 요청이 사용할 수 없는 Method일 경우
500	Server error	서버에 문제가 있을 경우  사용하는 응답코드

200 OK

요청성공

 

201 상태코드 Created

• POST, PUT 요청에대한 응답으로 많이 사용합니다. 200과의 요청성공은 같지만, 성공후 새로운 값이 생성됐다는 의미를 가지고 있습니다.
• 요청 성공해서 새로운 리소스가 생성됐고, 새로운 리소스는 응답의 Location 헤더 필드 값으로 식별

202 상태코드 Accepted

• 비동기방식일때 사용하는데, 요청에 대한 처리가 언제끝날지 모르기 때문에 202 코드를 반환합니다.
• 배치 처리같은 곳에서 사용
• 예로들어 요청 접수 후, 1시간 뒤에 배치 프로세스가 요청을 처리함

204 No  Content

요청 성공했지만, 서버의 응답으로 아무 데이터가 없을때 

 

3XX Redirection

요청을 완료하기 위해 유저 에이전트(웹브라우저)의 추가 조치가 필요할 때 

웹 브라우저는 3xx 응답의 결과에 location 헤더가 있으면  자동으로 이동함

 

영구 리다이렉션 : URL 변경

일시적 리다이렉션: URL 변경 x

 

301 영구 리다이렉션 

예) POST /event -> GET /new-event

리다이렉션 후 값이 사라짐

GET으로 변경

 

308 영구 리다이렉션

POST /event -> POST /new-event

리다이렉션 후 값, METHOD 을 유지 

 

302 일시적 리다이렉션

리다이렉션 후 값이 사라짐

GET으로 변경

 

307 일시적 리다이렉션

리다이렉션 후 값, METHOD 을 유지 

 

PRG : Post/React/Get

POST로 주문 버튼을 누르고 주문 프로세스가 진행 된 후 새로 고침을 하면?

중복 주문이 들어갈 수가 있습니다.

 

PRG 일시적인 리다이렉션 을 사용하면

• POST로 주문 후  새로고침으로 인한 중복 주문 방지 
• POST로 주문 후  주문 결과 페이지를 GET메서드로 리다이렉트
• 새로고침을해도 GET 으로 조회
• 중복주문 대신 결과 화면만 GET으로 요청

예시 )

클라이언트 주문: POST /order ->

서버 응답: 302 Found Location: GET /order_result/123 ->

새로고침 : GET /order_result/123 ->

결과페이지만 보임

 

304 Not Modified

클라이언트는 로컬 PC에 저장된 캐시를 재사용합니다.

캐시로 리다이렉트합니다.

 

400 상태코드 (클라이언트 오류)

• 유효성 검사를 통해 유효하지 않은 정보를 차단했다는 응답을 반환합니다.
• 예시) validation 체크 int로 넘어와야하는데 string으로 넘어왔을 때

401 상태코드

• 로그인하지 않은 유저가 로그인했을 때에나 해당 유저가 권한 없는 메뉴에 접근했을 때 반환하는 코드입니다.
• 로그인하지 않은: 인증(Authentication)
• 유저가 권한 없는: 인가(Authorization) 

403 Forbidden

서버가 요청을 이해했지만 승인을 거부

 

404 Not found

요청 리소스를 찾을 수 없음

# Ajax 사용시 요청 방법

ajax type을 사용하려는 method를 넣어서 사용합니다.

$.ajax({
    url : "/user",
    type : "PUT",
    data : $("#id").val(),
    dataType : "text",
    success: function(e) {
    }
});

# HTML form에서 Http Method 사용방법

HTML form은 PUT, PATCH, DELETE Action을 지원하지 않습니다. 따라서 _method의 숨겨진 필드를 지정해야 합니다.

<form action="/user" method="POST">
    <input type="hidden" name="_method" value="PUT">
</form>

# 결론

REST API는 누군가가 공식적으로 발표한것이 아니라, 단지 논문을 통한 소개이기 때문에 명확한 규칙, 정책등의 표준으로 나와있지 않습니다.

그러므로 개발자의 기준마다 각기 다른 URL이 정의 될 수 있고, 설계나 구현에서 어려움을 겪을수 있습니다. 구글, 네이버에서 지원하는 API들로만 봐도 정확하게 REST를 따르지 않습니다.

하지만 깔끔하게 디자인된 API는 서비스의 이익을 창출 할 수 있으며, API의 이해, 호환성을 높여 개발의 질을 높일 수 있습니다. 

 

 

 

---

 

HTML FORM 과 함께 사용 시 

• 회원 목록 /members -> GET
• 회원 등록 폼 /members/new -> GET 
• 회원 등록 /members/new, /members -> POST  ( /members/new 개인적 선호 )
• 회원 조회 /members/{id} -> GET
• 회원 수정 폼 /members/{id}/edit -> GET 
• 회원 수정/members/{id}/edit, /members/{id} -> POST (members/{id}/edit 개인적 선호 ) 
• 회원 삭제 /members/{id}/delete -> POST (delete method를 사용못할 때 post)

 

• HTML FORM은 GET, POST만 지원
• 컨트롤 URI 
  • GET, POST만 지원하므로 제약이 있음
  • 이런 제약을 해결하기 위해 동사로 된 리소스 경로 사용 
  • POST의 /new, /edit, /delete가 컨트롤 URI
  • HTTP 메서드로 해결하기 애매한 경우 사용(HTTP API 포함)