REST API

수툴리 양·2021년 10월 4일

TIL(2)

목록 보기

7/8

Keyword & overview

What is 'Representation' in REST API?
http 표현 헤더를 생각해보면, 요청/응답 되는 메시지(리소스/데이터) 의 데이터형식 등이 담겨 있음. 그 '표현' (= representation) 이란?
[원문] ... REST uses various representations to represent a resource where Text, JSON, XML. The most popular representations of resources are XML and JSON.
예시(request-response)

	//요청메시지
        GET https://example.org/greeting
        Host: example.org
        Accept: text/plain, text/html; q=0.9 *; q=0.1
        Accept-Language: en, ko; q=0.9, *; q=0.1

	//응답메시지
        HTTP/1.1 200 OK
        Content-Length: 6
        Date: Sun, 19 Mar 2017 10:20:47 GMT
        Last-Modified: Sun, 19 Mar 2017 08:00:00 GMT
        Content-Type: text/plain
        Content-Language: en
        
        hello World // body(본문)

서버가 전송해준 응답(body)은 사실 리소스가 아님. representation data이다.
GET 메서드 정의: The GET method requests transfer of a current selected representation for the target resource.
URI가 가리키는 타깃 리소스 대한 특정 시점의 상태를 반영하고 있는 정보를 응답
응답 메시지 body(본문)이 "hello world"라는 text라면 이건 representaion data.
표현 헤더에 "Content-Type: text/plain" 와 같은 → representation metadata
🔗 참고 블로그(2017)
이러한 representational data는 선택되는 것 (사전 협상- 'Accept-Language: ko' 과 같 헤더를 포함시켜 GET요청을 보낸다면, 서버가 한국어로 된 적절한 representation data를 응답으로 전송
*URI가 동일하다면 같은리소스이다. 여러 리소스 중 하나가 선택된 것이 아님
- 이 representation은 REST에서 온 것. Representational State Transfer 의미를 살펴보면 웹 앱의 상태를 전송 한다는 것
  *transfer: network component 간 전송

주의) state라는 동일한 단어로 표현하지만, 웹앱의 상태와 리소스의 상태는 다름. 웹앱 상태는 페이지A를 렌더링하다가 B를 렌더링하는 것으로 바뀐 그 상태

URI vs URL
-URI(uniform resource identifier)는 네트워크 상 리소스의 위치를 알려주기 위한 규약? *인터넷 프로토콜 관련
-URL(uniform resource locator)는 인터넷에 있는 리소스의 유일한 주소? URI가 상위 개념, URL이 포함된다고 보면 됨

좋은 예인지는 모르겠지만:
https://example.com/one?id=123 의 경우 URL은 https://example.com/one 까지이고, 내가 원하는 정보에 도달하기 위해서는 ?id=123이라는 식별자가 필요한 것. 이 또한 URI이지만 URL은 아닌것.

semantic 의미론적 이름에서 '역할'을 유추할 수 있는 명명 형식. 그냥
tag를 쓰기보다는 tag로 쓴다든지
retrieve 검색하다 API란 앱의 소프트웨어를 구성하고 통합하기 위한 프로토콜 및 정의들의 모이다. 정보 제공자와 사용자 간의 정보를 주고받는(요청-응답) 계약으로도 볼 수 있고. 예를 들어 날씨 서비스의 경우 사용자는 zipcode를 요청에 보내고 제공자는 최고기온, 최저기온 으로 응답을 전송할 수 있다. 정보를 검색하거나 어떤 기능을 수행하기 위해 컴퓨터나 시스템과 커뮤니케이션이 필요할 때 API가 그 기준이 되어 토대로 요청을 이해하고 충족하는 응답을 전송시켜줄 것이다.

RESTful 한 API 란?

클라이언트-서버 구조(클라이언트, 서버, 리소스로 구성된)에서, http를 통해 요청 및 응답 전송
'무상태성 Stateless' 서버에 클라이언트 상의 정보 state가 저장되면 안되며, 각 요청은 독립적임
클라이언트가 응답을 캐싱할 수 있어야 함
컴포넌트 간 일관된 인터페이스. 정보가 일관된 형식으로 전송되어야 함
- 요청된 리소스는 개별적으로 식별가능해야 하며, 클라이언트에 전달된 표현데이터와 분리되어야 함
- 표현데이터만으로도 클라이언트 상에서 리소스를 조작가능하다. 표현데이터가 리소스를 다루는 정보를 충분히 포함하고 있음.
서버의 계층구조는 클라이언트 측에서 알 수 없음.

Why use URL parameters over request body in API?

url 파라미터와 body 파라미터는 서로 다른 목적으로 사용
GET 메서드는 데이터를 검색(조회)해 오고(retrieve back) 싶을 때 쓰는 메소드로. 데이터 레코드를 변경하지 않음, 그러므로 body parameter를 passing하지 않는다.
원문(스택오버플로우) The GET method will not pass body parameter and hence whatever filter parameters passed to API will be through URL parameters.
정보를 변경(update)하는 목적: POST나 PUT 메서드 사용, parameter 값은 ? input이 없거나 single parameter 가 될 수 있다.

🤔 고민해볼 주제들..

What are the best practices: args in query string vs in request body vs url path

In the request body - As part of a json body, or other MIME type

In the query string - e.g. /api/resource?p1=v1&p2=v2

As part of the URL-path - e.g. /api/resource/v1/v2

⇒ Path Variable과 Query Parameter를 각각 언제 사용해야 하는가?

만약 어떤 resource를 식별하고 싶으면 Path Variable을 사용하고, // (a)
정렬이나 필터링을 한다면 Query Parameter를 사용하는 것이 Best Practice이다. // (b)

/users  # 사용자 목록을 가져온다.
/users?occupation=programer  # 프로그래머인 사용자 목록을 가져온다.  // (b)
/users/123  # 아이디가 123인 사용자를 가져온다.  // (a)

*기본적인 CRUD 기능을 위해서, 또 다른 URL이나 query parameter를 정의할 필요는 없음! 대신 원하는 기능에 맞게 HTTP 메소드를 바꾸어 사용하면 됨!

/users [GET] # 사용자 목록을 가져온다.
/users [POST] # 새로운 사용자를 생성한다.
/users/123 [PUT] # 사용자를 갱신한다.
/users/123 [DELETE] # 사용자를 삭제한다.

거의 모든 CRUD 프로세스를 추가적인 endpoint(예를 들어 users/create) 또는 query parameter(예를 들어 users?action=create) 없이 수행할 수 있는 것임. 메서드의 구분으로 단순화되고, 예측이 가능하다.

참고 🔗 블로그 🔗 원문

읽어볼 자료

본문

REST

1. REST 란?

Representational State Transfer 🔗 Wikipedia

www 개발 및 설계를 위한 소프트웨어 아키텍처이다.

웹과 같은 Internet-scale distributed hypermedia system의 아키텍처가 어떻게 (behave)해야하는지 제약조건들의 모음이다.

자세히 컴포넌트 간 상호작용의 확장성, uniform 인터페이스, 컴포넌트의 독립적 배포~~(재사용성?)~~ 을 강조하는 형식임, 층층이 레이어된 구조를 생성하고, 캐싱을 활용함으로써 사용자가 느끼는 latency를 감소하고 보안을 강화 + encapsulate legacy system
엄격한 의미로 REST는 네트워크 아키텍처 원리의 모음이다. 여기서 '네트워크 아키텍처 원리'란 리소스를 정의하고 리소스에 대한 주소를 지정하는 방법 전반을 일컫는다.
간단한 의미로는, 웹 상의 자료를 HTTP위에서 SOAP이나 쿠키를 통한 세션 트랙킹 같은 별도의 전송 계층 없이 전송하기 위한 아주 간단한 인터페이스를 말한다.

REST원리를 따르는 시스템을 RESTful하다고 말한다.

REST의 주요 목표

구성 요소 상호작용의 규모 확장성(scalability of component interactions)
인터페이스의 범용성 (Generality of interfaces)
구성 요소의 독립적인 배포(Independent deployment of components)
중간적 구성요소를 이용해 응답 지연 감소, 보안을 강화, 레거시 시스템을 인캡슐레이션 (Intermediary components to reduce latency, enforce security and encapsulate legacy systems)

6가지 제약 조건 (Architectural constraints)

When these constraints are applied to the system architecture, it gains desirable non-functional properties, such as performance, scalability, simplicity, modifiability, visibility, portability, and reliability. A system that complies with some or all of these constraints is loosely referred to as RESTful

Client-Server architecture : 아키텍처를 단순화시키고 작은 단위로 분리(decouple)함으로써 클라이언트-서버의 각 파트가 독립적으로 개선될 수 있도록 해준다.
Statelessness : 각 요청 간 클라이언트의 콘텍스트가 서버에 저장되어서는 안 된다.(무상태성)
Cacheability: www에서와 같이 클라이언트는 응답을 캐싱할 수 있어야 한다.
❇︎잘 관리되는 캐싱은 클라이언트-서버 간 상호작용을 부분적으로 또는 완전하게 제거하여 scalability(확장성)와 성능을 향상시킨다.
Layered system : 클라이언트는 보통 대상 서버에 직접 연결되었는지, 또는 중간 서버를 통해 연결되었는지를 알 수 없다. 중간 서버는 로드밸런싱 기능이나 공유 캐시 기능을 제공함으로써 시스템 규모 확장성을 향상시키는 데 유용하다.
Uniform Interface : 일관된 인터페이스로 분리되어야 함
- Resource identification in requests - URI를 사용하는 등의 요청request 내 개별 리소스를 식별 가능해야 함. 예를들어 서버는 db데이터 자체를 전송x, 레코드를 html, xml, json 등의 형식으로 전송. 즉 클라이언트가 받는 응답 내 정보와 리소스는 별개라는 의미같다. 개념적으로 분리되어 있다는.
- Resource manipulation through representations - 메시지를 통한 리소스 조작이 가능하다. 클라이언트가 리소스를 지칭하는 메시지와, 어떤 특정 메타데이터를 가지고 있으면 서버 상의 해당 자원 변경, 삭제를 할 수 있는 충분한 정보를 가진 것임
- self-descriptive messages - 각 메시지는 자신을 어떻게 처리해야 하는지에 대한 충분한 정보를 포함해야 한다.
Code on demand(optional)

Architectural Structure

: 클라이언트는 URI를 통해서만 리소스에 접근이 가능함.
클라이언트는 URI 를 가지고 요청을 보내고, 서버는 리소스의 표현데이터를 응답으로 전송

REST API 구조는 인터넷계층에서 사용할 수 있도록 설계 되었으므로, 클라이언트-서버 간 결합이 경량(loose)이어야 함. → 대규모 채택이 용이하도록. 이는 엔티티를 캡슐화하여 리소스를 정의함으로써 서버측에 추상화된 계층을 형성함으로써 가능한 것.

[원문]
it is designed for Internet-scale usage, so the coupling between the user agent (client) and the origin server must be as lightweight (loose) as possible to facilitate large-scale adoption. This is achieved by creating a layer of abstraction on the server by defining resources that encapsulate entities (e.g. files) on the server and so hiding the underlying implementation details (file server, database, etc.).
...중략
Clients can only access resources using URIs. In other words, the client requests a resource using a URI and the server responds with a representation of the resource. Thus, a resource is manipulated through hypertext representations transferred in messages between the clients and servers.
...후략

2. RESTful API

: REST(아키텍처)원리의 조건을 따르는 API

-A REST API (RESTful API) is an application programming interface (API or web API) that conforms to(adheres to) the constraints of REST architectural style and allows for interaction with RESTful web services

-Web service APIs that adhere to the REST architectural constraints are called RESTful APIs

클라이언트에서 RESTful API를 통해 요청을 보내면, requester나 엔드포인트로 리소스의 (현재)state에 대한 표현데이터를 전송(transfer)함

이 표현데이터라는 정보는 http를 통해 여러 포맷 중 하나로 전달됨(JSON/ HTML 등등) -JSON이 자연어와 기계어 모두 readable하므로 흔히 쓰임

RESTful API http요청에 있어서 헤더와 parameter가 중요. 메타데이터나, 인증권한, URI, 캐시, 쿠키 등의 식별자이므로.

🌟 RESTful 하게 API를 작성한다는 것 🌟
: RESTful한 api 란

클라이언트-서버 구조(클라이언트, 서버, 리소스로 구성된)에서, http를 통해 요청 및 응답 전송

'무상태성 Stateless' 서버에 클라이언트 상의 정보 state가 저장되면 안되며, 각 요청은 독립적임

클라이언트가 응답을 캐싱할 수 있어야 함

컴포넌트 간 일관된 인터페이스. 정보가 일관된 형식으로 전송되어야 함

요청된 리소스는 개별적으로 식별가능해야 하며, 클라이언트에 전달된 표현데이터와 분리되어야 함

표현데이터만으로도 클라이언트 상에서 리소스를 조작가능하다. 표현데이터가 리소스를 다루는 정보를 충분히 포함하고 있음.

서버의 계층구조는 클라이언트 측에서 알 수 없음.
🔗 원문

http 기반 RESTful APIs 예
- a base URI, such as http://api.example.com/;
- standard HTTP methods (e.g., GET, POST, PUT, and DELETE);
Semantics of HTTP methods
*semantic:'의미론적', 즉 메서드 이름에서 역할이 드러나는
The following table shows how HTTP methods are intended to be used in HTTP APIs, including RESTful ones.
[Http method] : [description]
- GET: get a representation of the target resource's state
- POST: let the target resource process the representation enclosed in the request.
- PUT: create or replace the state of the target resource with the state defined by the representation enclosed in the request.
- DELETE: delete the target resouce's target