[IT개념] Rest API

Rest(Representational State Transfer)

웹서비스가 어떻게 동작해야 하는지에 대한 설계 원칙 또는 아키텍처 스타일.

웹의 기존 기술과 HTTP 프로토콜을 그대로 활용한다.

네트워크 상에서 클라이언트와 서버간의 통식 방식 중 하나이다.

 

Rest 구성요소

1) 자원(Resource) : URI

모든 자원에는 고유한 ID가 있고, 이 자원은 Server에 존재한다.

ID는 /users/:user_id와 같은 HTTP URI다.

2) 행위(Verb) : HTTP Method

HTTP 프로토콜은 GET, POST, PUT, DELETE와 같은 메서드를 제공한다.

3) 표현(Representation of Resource)

클라이언트가 자원의 상태에 대한 조작을 요청하면 서버는 적절한 응답을 보낸다.

하나의 자원은 JSON, XML, TEXT 등의 여러 형태의 표현으로 나타낸다.

 

Rest API

API는 데이터와 기능의 집합을 제공하여 서로의 정보를 교환가능하게 하는 것이다.

Rest API는 Rest 기반으로 서비스 API를 제공한 것으로 Open API나

마이크로 서비스를 제공하는 업체들 대부분이 Rest API를 제공한다.

 

Rest API 설계 규칙

리소스 원형

1) 도큐먼트(Document)

하나의 객체 인스턴스, 데이터베이스 레코드와 유사한 개념.

사용자의 정보나 상품 정보 등이 도큐먼트에 포함된다.

// GET /users/123 : 특정 사용자의 ID값을 이용해 도큐먼트를 가져오는 요청이다.

// 실제로 가져온 JSON = 도큐먼트
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}

 

2) 컬렉션(Collection)

서버에서 관리하는 리소스들의 집합. 여러개의 도큐먼트를 포함하는 디렉토리 역할.

새로운 도큐먼트를 생성하거나 도큐먼트의 목록을 조회할 때 사용된다.

// GET /users : users라는 컬렉션에 속하는 사용자들의 목록을 가져오는 요청이다.

//실제로 반환된 JSON = user 컬렉션에 포함된 여러 사용자 도큐먼트
[
  {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"
  },
  {
    "id": 124,
    "name": "Jane Smith",
    "email": "jane@example.com"
  }
]

 

3) 스토어(Store)

클라이언트 측에서 관리되는 리소스들의 저장소.

캐시, 장바구니처럼 사용자가 소유하는 데이터들이 스토어에 해당된다.

// GET /shopping-carts/567/items
// : shopping-carts 스토어에서 특정 사용자(id: 567)의 장바구니 안 아이템을 조회하는 요청이다.

//실제로 반환된 JSON
[
  {
    "product_id": 201,
    "name": "Laptop",
    "quantity": 1
  },
  {
    "product_id": 202,
    "name": "Headphones",
    "quantity": 2
  }
]

 

설계 규칙

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

• 동사보다는 명사, 대문자보다는 소문자를 사용한다. ex) Used/123 (x) users/123 (o)
• 도큐먼트는 단수명사, 컬렉션과 스토어는 복수명사를 사용한다. ex) member/1 (x) members/1 (o)

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

• URI에는 HTTP Method가 들어가면 안된다. ex) GET/users/delete/1 (x) DELETE/users/1 (o)
• URI에 행위에 대한 동사표현이 들어가면 안된다. ex) POST/users/insert/1 (x) POST/users/1(o)
• 경로 중 변하는 부분은 유일한 값(id)으로 대체한다. ex) DELETE/users/12

3. 슬래시(/)는 계층 관계를 나타낼 때 사용한다. ex) http://localhost:8080/foods/pizza

4. URI 마지막 문자로 슬래시를 포함하지 않는다. ex) http://localhost:8080/foods/pizza/ (x)

5. 하이픈(-)은 불가피하게 긴 URI 경로의 가독성을 높이는데 사용한다.

6. 언더바는(_) URI에 사용하지 않는다.

7. 파일 확장자는 URI에 포함하지 않는다.  ex) http://localhost:8080/foods/pizza.jpg (x)

8. 리소스간에 연관관계가 있는 경우 작성 방법은 다음과 같다

• /리소스명/리소스 ID/관계가 있는 다른 리소스명(일반적으로 소유(has)의 관계일 때)
  ex) GET /users/{userid}/devices (o)
  ex) GET /users/{memberid}/devices (x) >> users 뒤에는 일반적으로 user의 id가 와야한다.

9. URI에 리소스, id 이외의 정보가 들어가지 않게 한다. ex) GET /users/{username} (x)

 

 

참고한 링크

[간단정리] REST, REST API, RESTful 특징