[WEB] RESTful API

Posted 1. March 2022. 10 min read.

RESTful API

갑자기 기억이 안나서 다시 작성.

REST란?

Representational State Transfe라는 용어의 약자입니다.
자원을 URI로 표시하고 해당 자원의 상태를 주고 받는 것을 의미합니다.

REST의 구성 요소는 아래로 이루어졌습니다.

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

즉 Rest는 URI를 통해 자원을 표시하고, HTTP METHOD를 이용하여 해당 자원의 행위를 정해주며 그 결과를 받는 것을 의미합니다.

REST의 특징

1) Uniform (유니폼 인터페이스)

Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말합니다.

2) Stateless (무상태성)

REST는 무상태성 성격을 갖습니다. 즉 작업을 위한 상태정보를 따로 저장하고 관리하지 않습니다.
세션 정보나 쿠키정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만 단순히 처리하면 됩니다.
서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해집니다.

3) Cacheable (캐시 가능)

REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능합니다.
즉, HTTP가 가진 캐싱 기능이 적용 가능합니다. HTTP 프로토콜 표준에서 사용하는 Last-Modified태그나 E-Tag를 이용하면 캐싱 구현이 가능합니다.

4) Self-descriptiveness (자체 표현 구조)

REST의 또 다른 큰 특징 중 하나는 REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있다는 것입니다.

5) Client - Server 구조

REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어들게 됩니다.

6) 계층형 구조

REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 합니다.

REST API란?

Rest 기반의 규칙들을 지켜서 설계된 API를 Rest API 혹은 Restful API이라고 합니다.

REST API 설계 규칙

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

자원의 이름은 동사보다는 명사를 사용합니다.
URI는 자원을 표현하는데 중점을 두어야 하기 때문에 행위에 대한 표현이 들어가면 안됩니다.
행위에대한 동사 표현이 들어가면 안됩니다.

    GET /users/321

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

URI에 자원의 행위에 대한 표현이 들어가지 않는 대신 HTTP METHOD를 통해 대신한다.

   GET /users/321 321 ID를 가진 유저 정보를 가져오기
   DELETE /users/321 321 ID를 가진 유저 정보를 삭제하기
   POST /users 유저를 생성하기

METHOD	역할
POST	POST를 통해 해당 URI를 요청하면 리소스를 생성합니다.
GET	GET를 통해 해당 리소스를 조회합니다. 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다.
PUT	PUT를 통해 해당 리소스를 수정합니다.
PATCH	PATCH를 통해 자원의 일부를 수정합니다.
DELETE	DELETE를 통해 리소스를 삭제합니다.

3. 슬래시 (/)는 계층 관계를 나타내는데 사용합니다.

   http://restapi.test.com/users/rooms
   http://restapi.test.com/users/board

4. URI 마지막은 슬래시(/)를 사용하면 안됩니다.

   http://restapi.test.com/users/rooms/ [X]
   http://restapi.test.com/users/rooms  [O]

5. 하이픈 (-)은 URI의 가독성을 높이는데 사용합니다.

불가피하게 긴 URI를 사용하게 될 경우 하이픈을 이용하여 가독성을 높입니다.

6. 언더바(_) 혹은 밑줄은 URI에 사용하지 않습니다.

밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지기도 합니다.
그래서 대신 언더바를 사용하지 않고 하이픈을 이용합니다.

7. URI는 경로에는 소문자가 적합하다.

URI 경로에는 대문자 사용을 피해야합니다.
대소문자에 따라 각자 다른 리소스로 인식하기 때문입니다.
RFC3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문이다.

8. 파일 확장자는 URI에 포함하지 않는다.

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

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

   GET : /users/{userid}/devices

이 규칙 중 가장 중요한 규칙은 아래 입니다.

첫 번째, URI는 정보의 자원을 표현해야 한다.
두 번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

좀 더 자세하게 확인하기 위해서는 다음 링크를 참고하면 좋습니다. LINK

## RESTful API란?

위에서 설명했던 REST를 REST답게 쓰기 위한 방법이지만 누군가가 공식적으로 발표한 것이 아니고 그저 개발자들이 비공식적으로 의견을 제시한 것이라 명확한 정의는 없습니다.
하지만 RESTful의 목적은 이해하기 쉽고 사용하기 쉬운 REST API를 만드는 것입니다.

CRUD	HTTP METHOD	URI
user들을 표시	GET	/users
user 하나만 표시	GET	/users/:id
user를 생성	POST	/users
user를 수정	PUT	/users:id
user를 삭제	DELETE	/users:id

잘못된 경우는 다음과 같습니다.

Restful 하지 못한 경우
CRUD 기능을 전부 POST METHOD로만 처리하는 API
URI에 자원과 id외 정보가 들어가는 경우

   PUT /users/update-nickname [X]
   PUT /users/:id/nickname [O]

HTTP 응답 상태 코드

잘 설계된 REST API는 URI만 잘 설계된 것이 아닌 그 리소스에 대한 응답을 잘 내어주는 것까지 포함되어야 합니다.
정확한 응답의 상태코드만으로도 많은 정보를 전달할 수가 있기 때문에 응답의 상태코드 값을 명확히 돌려주는 것은 생각보다 중요한 일이 될 수도 있습니다.

상태코드	성공
200	클라이언트의 요청을 정상적으로 수행함.
201	클라이언트에게 생성 작업을 요청 받았고, 생성 작업을 성공함.
204	요청은 성공 했지만 응답할 콘텐츠가 없음.

상태코드	리다이렉션
301	클라이언트가 요청한 리소스에 대한 URI가 영구적으로 변경되었을 때 사용함.
302	301과 같으나 임시적으로 주소가 바뀌었을 경우 사용함.
304	이전에 방문했을 때의 요청 결과와 다르지 않을 경우 사용함. 캐시된 페이지를 그대로 사용.
307	임시 페이지로 리다이렉트.

상태코드	클라이언트 오류
400	클라이언트가 올바르지 못한 요청을 보냄.
401	로그인을 하지 않아 페이지를 열 권한이 없음.
403	금지된 페이지, 로그인을 하든 안하든 접근할 수 없음. (관리자 페이지)
404	찾을 수 없는 페이지, 주소를 잘 못 입력했을 때 사용함.
	403 대신에 사용할 수도 있음.(해커들의 공격을 방지하고자 페이지가 없는 것처럼 위장함)
408	요청 시간이 초과됨.
409	서버가 요청을 처리하는 과정에서 충돌이 발생한 경우. (회원가입 중 중복된 아이디인 경우)
410	영구적으로 사용할 수 없는 페이지.

상태코드	서버 오류
501	해당 요청을 처리하는 기능이 만들어지지 않음.
502	서버로 가능 요청이 중간에서 유실된 경우.
503	서버가 터졌거나 유지 보수 중 (유지 보수 중일때는 유지 보수중이라는 것을 알려주는 페이지로 전송해주는 것이 좋음)
504	서버 게이트웨이에 문제가 생겨 시간 초과가 된 경우.
505	HTTP 버전이 달라 요청이 처리할 수 없음.

References

To be a Pro in Web developer

📘 Linkedin 📚 TIL 💻 GitHub ✨ Portfolio