[개념] REST API의 특징 및 API URL 작성법

REST API 란?

REST(Representational State Transfer) API는 웹과 같은 분산 하이퍼미디어 시스템을 위해서 만들어진 아키텍처 스타일이다. 

REST API는 웹에서 데이터를 전송하는 방법을 정의하는 데 중점을 두고 있으며, 웹 기술과 HTTP 프로토콜을 사용한다.

 

 

REST API 특징

 

1. 균일한 인터페이스

REST API 아키텍쳐를 단순화하고 가시성을 높이기 위해서는 인터페이스에 일반성 원칙을 적용시켜야한다.

REST 인터페이스를 만들기 위해 4가지 추가 제약조건이 있다.

• 리소스 식별 - 인터페이스는 클라이언트와 서버 간의 상호 작용에 관련된 각 리소스를 고유하게 식별해야 한다
  +) 리소스를 식별하는 수단으로는 Url를 많이 사용한다.
• 표현을 통한 리소스 조작 – 클라이언트는 통일된 표현방법으로 리소스를 조작한다.
  +) GET, POST, DELETE, PUT, PATCH
  
  
• 메세지 설명 – 각 리소스 정보에는 메시지 처리 방법을 설명할 수 있는 정보가 포함되야한다. 
  +) 해당 url를 통해 무엇을 더 할 수 있는지 설명을 적어준다.
  

  {
    "id": 1,
    "name": "SanghyunDal",
    "links": {
      "self": "/users/123", //현재 url
      "put": "/users/123", // 업데이트 url
      "delete": "/users/123" //삭제 url
    }
  }

• 애플리케이션 상태의 엔진으로서의 하이퍼미디어 – 클라이언트는 애플리케이션의 초기 URI만 가지고 있어야 합니다. 
  +) 초기 url를 통해 다음 작업에 대한 url을 동적으로 알아가야한다.

 

2. 클라이언트-서버 구조

클라이언트는 서버로부터 데이터를 받아서 사용자에게 보여주는 역할을 하고, 서버는 클라이언트의 요청에 따라 데이터를 보내준다.

 

+) 클라이언트와 서버는 독립적으로 의존성 낮게 개발되어야한다.

 

3. 무상태성

클라이언트는 서버에게 데이터를 요청할 때, 이전에 했던 요청과는 별개의 요청으로 판단된다.

그래서 매 요청마다 요청과 관련된 모든 정보를 서버에 보내어 그에 해당하는 답변을 받는다.

 

+) 서버는 클라이언트가 전에 보냈던 요청에 대해 기억하지 않기 때문에, 매 요청을 보낼때마다 요청이 필요한 조건을 모두 url에 담아서 보내야한다.

 

4. 캐시 가능

REST API는 HTTP 프로토콜을 기반으로 하기 때문에 HTTP의 캐싱 기능을 사용할 수 있다.

캐싱 기능을 사용하면 클라이언트 측에서 데이터를 저장하여 서버의 부하를 줄이고, 응답시간을 단축시킬 수 있게 된다.

 

+) http 요청의 헤더부분에 'Cache-Control'과 관련하여 값을 주어 캐시 기능을 사용한다.

 

5. 계층화된 시스템

클라이언트와 서버 사이에 다양한 시스템을 두어 추가적인 기능을 확장할 수 있다.

예로는 프록시서버, 캐싱서버, 데이터베이스서버 등이 있을 수 있다.

+) 추가적인 기능 : 보안 강화, 성능 향상, 유지보수 등등

 

 

주요 HTTP 메소드와 목적

 

• GET: 서버에서 리소스를 조회한다. 데이터를 변경하지 않고, 조회만 한다.
• POST: 서버에 리소스를 생성한다.
• PUT: 서버의 리소스를 업데이트하고, 리소스가 존재하지 않으면 새로 생성할 수도 있습니다.
• DELETE: 서버의 리소스를 삭제한다.
• PATCH: 리소스의 일부를 업데이트한다.

 

 

API url 작성시 유의할 점

 

1. 일관성 유지

url 구조와 네이밍 규칙을 일관되게 유지하여 API 동작을 예측할 수 있어야한다.

 

2. url은 직관적인 명사와 복수형을 사용한다.

- url은 동사보다는 명사로 구성해야한다. ex) /getUsers (x) -> /users (o)

- 리소스 이름은 명확하고 직관적으로 지어야하고 명사의 경우 복수형으로 사용한다. ex) /users , /products ...

 

3. RESTful한 원칙을 준수

각 HTTP 메소드 목적에 맞게 사용해야한다.

 

4. url의 쿼리 파라미터

url의 쿼리 파라미터를 사용하여 리소스를 필터링, 정렬, 페이징한다.

 

5. 하이픈(-)

url에서는 밑줄(_)을 사용하지 않고 하이픈(-)을 사용하여 구성한다.

 

6. HTTP 상태 코드

 

• 200 OK: 요청 성공
• 201 Created: 리소스 생성 성공
• 204 No Content: 요청 성공, 응답 본문 없음
• 400 Bad Request: 잘못된 요청
• 401 Unauthorized: 인증 실패
• 404 Not Found: 리소스 없음
• 500 Internal Server Error: 서버 오류

위의 상태코드를 잘 사용하여 클라이언트에게 요청에 대한 결과를 알려줘야한다.

 

 

7. 리소스간의 관계 표현

url에는 리소스 간의 계층적인 관계에 대한 정보도 포함되야한다.

 

ex) /users/111/products -> 111번의 아이디를 가진 유저 아래에 있는 물품이라는 것을 유추할 수 있다.

 

 

참고

https://restfulapi.net/

What is REST?: REST API Tutorial

https://kmkunk.tistory.com/139

REST API 설계 원칙

https://prohannah.tistory.com/156

RESTful API를 위한 6가지 원칙과 네이밍