[WEB] Rest API 와 설계

Rest API 란?

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

 

 

 

Rest 의 구성

자세한 내용은 아래에서 설명 하겠습니다.

• Resource(자원) :HTTP URI
• Representations: HTTP Message Pay Load
• Verb(행위) : HTTP Method

 

 

Resource(자원)?

• Rest 아키텍처는 모든 컨텐츠를 하나의 리소스로 다룬다.
• 파일, HTML 페이지, 이미지, 비디오 또는 동적 비즈니스 데이터 등등 자원이 될수 있다.
• REST는 다양한 표현을 사용하여 Text, JSON, XML이 있는 리소스를 나타낸다.
• 가장 많이 사용되는 리소스 표현은 XML과 JSON이다.

 

 

Representations(표현방법)

• REST의 리소스는 Object Oriented Programming의 유사한 개체이거나 데이터베이스의 엔티티와 같다.
• Resource 를 식별한 다음 표준 형식을 사용하여 해당 리소스를 어떻게 표현할지 정한다.Client 가 이해 할 수 있도록 정해진 형식으로 Resource를 보낸다.
• 하나의 자원은 여러개의 표현을 가진다.

 

XML 방식

<user> 
   <id>1</id> 
   <name>Tom</name>
   <age>23</age> 
</user>

 

JSON 방식

{ 
   "id":1, 
   "name":"Tom", 
   "profession":"23" 
}

참고: XML 이나 JSON은 절대 자원이 아니다, 자원의 표현이다.

 

 

자원을 표현하기 위한 좋은 방법

• Understandability(이해성):
  서버와 클라이언트 모두 리소스의 표현 형식을 이해하고 활용할 수 있어야 한다.
  
  
• Completeness(완전성):
  Resource 를 완전하게 나타 내어야 한다 Resource 는 계층 구조를 가질수 있다. 복잡하더라도 완벽하게 표현되어야 한다.
  
  
• Linkablity(연결성):
  Resource는 다른 리소스에 대한 연결을 가질 수 있으며, 형식은 이러한 상황을 처리할 수 있어야 한다.

 

 

 

Verb(행위)

행위는 Http 의 method 를 따른다.

 

대표적인 메소드

HTTP Method	URI	Operation
GET (Read)	http://localhost:8080/users	모든 유저를 가져온다.
POST (Insert)	http://localhost:8080/users/2	유저 2를 생성한다.
PUT (Update)	http://localhost:8080/users/2	유저 2를 업데이트한다.
DELETE (Delete)	http://localhost:8080/users/2	유저 2를 삭제한다.
OPTIONS (Read)	http://localhost:8080/users	웹서비스에서 수행가능한 연산을 나타낸다.
HEAD (Read)	http://localhost:8080/users	Header 만 리턴한다. Body는 포함하지 않는다.

참고: POST, PUT, DELETE 는 URI 가 동일 하지만 동작이 다르다 어떤메소드로 요청했는지에 따라 결정되기 때문이다.

 

 

 

REST의 특징

• Uniform interface (유니폼 인터페이스)
• Stateless (무상태성)
• Caching (캐시 가능)
• Self-descriptiveness (자체 표현 구조)
• Client - Server 구조
• 계층형 구조

 

 

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

아키텍처를 단순화하고 분리하므로 각 부분이 독립적으로 발전될수 있다.

특정언어나 기술에 제한이 없다.

모든 플랫폼에서 사용할수 있다.

 

그렇기 위해선 아래 4가지 규칙을 따라야 한다.

• 1. Identification of resources:
  (URI) 표준을 사용하여 리소스를 식별한다.
  
  
• 2. Manipulation of resources through these representations:
  HTTP 표준을 사용하여 통신한다. GET 읽기, POST 쓰기 등등
  
  
• 3. Self-descriptive messages:
  자체 표현 구조로 되어 있다
  고객은 의미 확인하여 데이터를 찾을 수 있다.
  서비스가 사용하는 애플리케이션별 데이터 구조를 알 필요가 없다.
• 4. Hypermedia as the engine of application state
  하이퍼링크 URI 템플릿을 사용하여 클라이언트를 애플리케이션별 URI 구조에서 분리한다.

 

 

Stateless (무상태성)

서버에서 클라이언트 상태를 유지하면 안된다.

 

장점

• 웹 서비스는 각 메서드 요청을 독립적으로 처리할 수 있다.
  
  
• 웹 서비스는 클라이언트의 이전 상호 작용을 유지할 필요가 없다.
  - 애플리케이션 설계를 단순화합니다.
  
  
• HTTP 자체가 상태 비저장 프로토콜이므로 RESTful 웹 서비스는 HTTP 프로토콜과 원활하게 작동한다.
  
  

단점

• 웹 서비스는 클라이언트의 상태를 저장하지 않기 때문에 각 요청에 대한 추가 정보를 얻어야 합니다.

 

 

Caching (캐싱)

• 캐싱은 클라이언트가 동일한 리소스에 대해서 서버 요청을 반복할 필요가 없도록 한다.
  - 서버 응답을 클라이언트 자체에 저장한다.
  
  
• 캐싱 수행 방법에 대한 정보가 있어야 한다.

 

 

 

Self-descriptiveness (자체 표현 구조)

• API 메시지 자체만 보고도 API를 이해할 수 있는 Self-descriptiveness 구조를 갖는 다는 것이다.

 

 

 

Client - Server 구조

• 클라이언트는 유저와 관련된 처리를, 서버는 REST api를 제공함으로써 각각의 역할을 구분한다.

 

 

계층형 구조

• 클라이언트는 REST API 서버만 호출한다.
• 서버는 로직처리, 사용자 인증, 암호화 등 계층을 추가해서 구조의 유연성을 이점으로 가질수 있다.

 

 

 

 

설계규칙

 

1. 심플하고 직관적으로 설계한다.

• API URL 을 보고 무슨 API 알수 있어야 한다.
• 길이는 짧게
• depth는 2까지

GET /members
GET /members/id

 

 

 

2. 동사가 아닌 명사로 설계한다.

• REST API 는 어떤 Entity 의 CRUD 를 정의 하는 개념이다.
• 대상은 명사가 되어야 한다.
• get, post 등 행위를 나타내는 동사는 사용하지 않는다.

 

나쁜예

POST /getMembers
POST /setMembers

 

좋은예

GET  /members
POST /members

 

 

 

3. 단수보다 복수를 사용하자

나쁜예

GET /member

 

좋은예

GET /members        전체회원 조회 
GET /members/id     특정ID를 가진 회원조회