REST API

REST API

REST API?

REST를 기반으로 만들어진 API입니다.
여기서 REST란 REpresentational State Transfer의 약자로, 대충 "대표 상태 전송"이라고 하겠습니다.

이 REST는 쉽게 말해 3가지의 요소로 구성됩니다.

• 자원(Resource) : 고유의 URI를 갖는다.
• 행위(Verb) : HTTP Method
• 표현(Representation) : 클라이언트가 HTTP Method로 자원을 조작 시 응답(JSON, XML, String...)을 표현한다.

---

1. REST API의 특징

1. Uniform Interface (일관된 인터페이스)
   모든 자원은 하나의 고유한 URI를 갖고 명확한 인터페이스로 구성되어
   HTTP Request를 호출할 수 있는 어떠한 기술, 플랫폼(Java, Go, Windows, Mac...)에서든 사용할 수 있습니다.
   
   
2. Stateless (무상태성)
   요청에 대한 상태 정보를 저장하지 않습니다.
   세션, 쿠키 등 별도로 저장을 하지 않기 때문에 요청만 처리하면 됩니다.
   이로 인해 구현이 단순해지고, 서비스의 자유도가 증가합니다.
   
   
3. Cacheable (캐시 가능)
   HTTP라는 웹 표준을 사용하고 있기 때문에 웹의 기본 인프라를 사용할 수 있습니다.
   그러므로, 캐시 기능을 사용하여 같은 요청(URI)이 반복적으로 수행될 때 더욱 효율적입니다.
   
   
4. Self-descriptiveness (자체 표현 구조)
   메시지가 보여주고자 하는 바를 명확하게 표현하여 보다 확실하게 요청에 대해 이해할 수 있습니다.
   예를 들어, "/users/1"라는 요청에 응답했을 때, Status Code와 Content Type 등을 통해 표시할 수 있습니다.
   
   
5. Client-Server Architecture (클라이언트-서버 구조)
   서버는 API의 제공, 클라이언트는 사용자에 대한 처리를 전담하는 구조입니다.
   이로 인해 서버와 클라이언트 간의 역할을 분명하게 구분할 수 있습니다.
   
   
6. Layered System (계층형 구조)
   클라이언트는 API를 호출할 때 대상 서버와 직접 통신하는 것인지, 중간 서버와 통신을 하는지 확인할 수 없습니다.
   이로 인해 서버는 로드밸런서, 프록시, 암호화 계층 등을 중간에 추가할 수 있습니다.

---

2. REST API 규칙

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

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

GET /users/delete/1

위의 URI는 REST를 지키지 않은 예입니다.
REST API에서의 URI는 자원만을 표기하고 행위는 HTTP Method를 이용합니다.

자원에 대한 행위는 HTTP Method로 표현한다.

위의 메서드를 REST API의 규칙에 맞게 수정한다면 아래와 같이 수정할 수 있습니다.
HTTP Method(GET, POST, PUT, PATCH, DELETE 등)를 이용하여 요청을 더욱 명확하게 해야 합니다.

DELETE /users/1

---

3. URI 디자인 가이드

3-1. URI의 마지막엔 슬래시(/)를 포함하지 않습니다.

ex) https://www.example.com/users/ (X)
    https://www.example.com/users  (O)

3-2. 슬래시(/)를 이용하여 계층 구조를 나타냅니다.

https://www.example.com/movies/action

3-3. 밑줄(_)은 사용하지 않습니다.

https://www.example.com/under_bar (하이퍼링크가 걸린다면, 언더바가 감춰져 /under bar로 보일 수 있다.)

3-4. 하이픈(-)을 사용하여 가독성을 높일 수 있습니다.

단어가 길다면 camelCase로 하지말고, kebab-case로 작성합니다.
https://www.example.com/long-string

3-5. URI는 소문자와 명사만을 사용하지 않습니다.

리소스를 설명할 땐 구체적인 명사를 사용하여 작성합니다.

3-6. 파일 확장자는 URI에 포함하지 않습니다.

https://www.example.com/users/1/thumbnail.jpg (X)
https://www.example.com/users/1/thumbnail     (O)

대신, HTTP Header를 이용하여 컨텐츠를 처리할 수 있도록 합니다.

GET /users/1/thumbnail HTTP 1.1
Host: www.example.com
Accept: image/jpg

3-7. 복수형을 사용합니다.

https://www.example.com/user/1  (X)
https://www.example.com/users/1 (O)

---

마지막으로, 잘 설계된 REST API는 리소스에 대한 응답을 정확하게 넘겨주어야 합니다.
이를 위해 HTTP 응답 코드를 적절히 부여할 수 있습니다.

상태코드
2XX	정상적으로 성공한 응답 코드 (200 OK, 201 Created ...)
3XX	리다이렉션 (301 Moved Permanently, 302 Found ...)
4XX	클라이언트 측에서의 잘못된 요청 (403 Forbidden, 404 Not Found ...)
5XX	서버 측의 에러 응답 (500 Internal server error ...)

정확한 HTTP Status Code는 링크된 페이지에 나열되어있으니 한 번쯤 읽어보는 것도 좋습니다.

---

4. 마치며...

기존에는 조금 모호하게 생각했던 부분들이 이번 포스팅을 통해 조금 더 정립되셨으면 좋겠습니다.
감사합니다.