[Network] REST와 REST API

제가 찾아 읽은 내용을 정리하는 공간입니다. 정확한 정보는 하단 레퍼런스를 참고해주세요.

1. HTTP API, HyperText Transfer Protocol

---

• HTTP 통신 규칙을 기반으로 API를 의미
• 웹과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍쳐의 한 형식

 

API, Application Programming Interface

• 어플리케이션이 어떤 프로그램이 제공하는 기능을 사용할 수 있도록 데이터와 정보를 교환하는 것
• 인터페이스이기 때문에, 어플리케이션 개발자에게는 API 기능을 수행하는데 필요한 부분만을 제공한다. 동시에 API는 요청에 따른 반환값을 제공할 뿐 내부의 구현은 숨긴다

 

2. REST, REpresentational State Transfer

---

REST 정의

• Representational State Transfer (표현적인 상태 전달)
  • 자원의 이름을 HTTP URI에 표현하고, 자원의 상태는 HTTP METHOD로 정의하는 방법
• REST는 HTTP 프로토콜을 그대로 사용하기에, HTTP의 장점을 최대한 활용 가능
• 네트워크 상에서 Server-Client 통신 방식을 사용

 

REST 구성 요소

1. Resource : URI
   • 자원은 HTTP URI로 구분한다
2. Verb : HTTP Method
   • HTTP Method : GET POST PUT DELETE
3. Representation of Resource 
   • Client가 자원과 행위를 요청하면, Server는 이에 맞는 응답(representation)을 보낸다
   • REST에서 자원은 주로 JSON과 XML과 같은 형태의 representation으로 나타낸다

 

REST 특징

1. Server-Client (서버-클라이언트 구조) : 서로 간 의존성이 줄어든다 (HTTP)
2. Stateless (무상태) : 서버는 클라이언트의 상태를 보존하지 않는다 (HTTP)
3. Cacheable (캐시 처리 가능) : 대량의 요청을 효율적으로 처리한다 (HTTP)
4. Layered System (계층화) : Server는 다중 계층으로 구성될 수 있으며, 구조적 유연성을 줄 수 있다. 
5. Uniform Interface (인터페이스 일관성) : URI로 지정한 자원에 대해 일관성 있고 한정적인 인터페이스로 수행한다
6. Code on demand : Server로부터 스크립트를 받아서 Client에서 실행한다. 반드시 충족할 필요없다 

 

 

3. REST API, REpresentaional State Transfer Application Programming Interface

---

REST API 정의

• REST를 기반으로 서비스 API를 구현한 것
• 조직 내 시스템의 확장성과 재사용성을 높일 수 있다

 

REST API의 원칙

1. 자원의 식별
   • 요청 내 기술된 개별 자원을 식별할 수 있다
2. 메시지를 통한 리소스 조작
   • 자원과 특정 메타데이터만 가지고 있다면, 서버 상의 자원을 조작할 수 있는 충분한 정보를 가지고 있는 것이다
3. 자기서술적 메서지
   • 각 메시지는 자신을 어떻게 처리해야하는지에 대한 충분한 정보를 포함한다
4. 애플리케이션의 상태에 대한 엔진으로서 하이퍼미디어(HATEOAS)
   • 하이퍼링크가 추가되어 다음에 어떤 API가 호출해야하는지를 해당 링크를 통해서 받을 수 있다
   • 클라이언트가 전적으로 서버와 동적인 상호작용이 가능하도록 하는 것

일반적인 API 응답

{
	"user_id" : 1000
}​

 

Hateoas가 적용된 API 응답

{
	"user_id" : 1000,
    	"links" : [
    	{	
        	"rel" : "self",
        	"href" : "http://localhost:8080/users/1000"
        }, {	
        	"rel" : "user-data",
        	"href" : "http://localhost:8080/users/1000/data"
        }
    ]
}

 

Resource

• document : 객체 인스턴스

http://api.example.com/users/{id}

• collection : 단일 document들의 묶음. 복수 형태로 표현

http://api.example.com/users

http://api.example.com/users/{id}/items

• store : client 입장의 저장소, client가 관리하는 형태

http://api.example.com/users/{id}/favorites

• controller : CRUD 외의 것을 표현하여 동사로 표현
  (method로 표현이 어려울 때, 대표적으로 PUT과 DELETE를 사용하지 못하는 경우 controller로 표현한다)

http://api.example.com/users/{id}/register

 

REST API 설계 기본 규칙

1. URI는 정보의 자원을 표현한다
   • 자원은 동사보다 명사를, 대문자보다 소문자를 사용한다
   • 자원은 document 이름으로 단수명사를 사용한다
   • 자원은 collection 이름으로 복수명사를 사용한다
   • 자원은 store 이름으로 복수명사를 사용한다
   • ex) GET /users/1
2. 자원에 대한 행위는 HTTP Method로 표현한다
   • URI에 HTTP Method/행위에 대한 동사 표현이 들어가면 안된다
     • URL에 동사를 쓰면 안되는 이유
       • 불필요한 중복
       • HTTP method와 URL에 표현한 동사와의 불일치
     • ex) GET /users/delete/1 -> DELETE /users/1
     • ex) GET /users/show/1 -> GET /users/1
   • 경로 부분 중 변하는 부분은 유일 값으로 대체한다
     • ex) 새로운 학생을 생성 : POST /students
     • ex) id가 4인 학생을 삭제 : DELETE /students/4

 

REST API 설계 규칙

1. 슬래시( / )는 계층 관계를 나타낸다
2. URI 마지막 문자로 슬래시를 포함하지 않는다
3. 하이픈( - )은 URI 가독성을 높이는데 사용한다
4. 언더바( _ )는 URI에 사용하지 않는다
5. URI 경로에는 소문자를 사용한다 (RFC 3986)
6. 파일 확장자는 URI에 포함시키지 않는다
   • Accept Header를 사용한다
   • ex) GET /users/3/photo.jpg (X)
   • ex) GET /users/3/photo Host: restapi.example.com Accept: image/jpg
7. 리소스 간에는 연관 관계가 있는 경우
   • /리소스명/리소스ID/관계가 있는 다른 리소스명
   • ex) GET /users/3/pencils (has의 관계를 표현할 때)
8. id는 하나의 특정 resource를 나타내는 고유값이다

 

4. RESTful

---

RESTful 이란

• RESTful은 REST 아키텍처로 구현한 서비스를 표현한다
  • REST API를 사용하는 웹 서비스는 RESTful하다
• 이해하기 쉽고 사용하기 좋은 REST API를 만드는 방법
• 성능 향상 보다는 일관적인 컨벤션을 통한 API의 이해도와 호환성을 높이기 위함

 

5. Reference

57 · Issue #2 · SangHakLee/sanghaklee.tistory.com

GitHub - WeareSoft/tech-interview: 🙍 tech interview

[Network] REST란? REST API란? RESTful이란? - Heee's Development Blog

API, HTTP API, REST API 차이

HTTP API vs REST API - 인프런 | 질문 & 답변

REST - 위키백과, 우리 모두의 백과사전

[Spring] Level3 REST API 구현을 위한 HATEOAS 적용

https://www.youtube.com/watch?v=RP_f5dMoHFc