study restful

1. 웹 서핑하기 & 2. 간단한 API

RESTful API

1장

  • 웹에서의 원칙 : 일반 사용자들이나, 자동화 소프트웨어 에이전트나 동일하게 작동한다.
  • URL : 데이터 접근 경로 ⇒ 각 URL은 하나의 리소스를 식별한다.
  • 브라우저가 리소스에 HTTP 요청을 보내면 서버는 응답으로 리소스의 표현(representation)을 반환한다.

주소 지정 가능성(addressability)

  • 하나의 URL은 단 하나의 리소스만 식별한다.
    • 플래시 인터페이스가 이를 어긴 대표적인 예시
  • 이 원칙은 모든 리소스는 각각 자신의 URL을 가져야 한다는 말

짧은 세션

  • HTTP 세션은 하나의 요청 동안 유지된다.
  • 요청이 발생하지 않으면 서버는 클라이언트의 존재를 모른다 ⇒ 무상태(statelessness)

자기 서술형 메시지

  • 요청에서 받은 리소스의 표현에는 보통 다음에 해야할 것도 포함되어 있다.

  • HTTP 메서드 : 클라이언트가 리소스에 무엇을 원하는지 서버에 알려주는 방법
  • GET, HEAD, POST, PUT, DELETE를 포함하여 총 8개
  • PATCH : 확장 메서드(이 외 새로운 메서드 정의는 권유되지 않음)

애플리케이션 상태

  • 애플리케이션 상태 in REST : ‘어떤 페이지에 와있는가?’, ‘어떤 상태고 다음에 어떤 동작을 수행할수 있는가’의 기준에서 현재 상황을 의미
  • 애플리케이션 상태의 전환 ⇒ 나타난 링크로 이동한다거나, 폼을 채운다거나…
    • 구현되어 있지 않은 상태의 전환은 불가능하다
    • 빈 페이지에서 POST를 보낼 수 없듯이..

리소스 상태

  • 말 그대로 리소스들의 상태
  • GET은 조회, POST는 새 상태를 추가하는 것
  • 클라이언트는 리소스 상태에 대해 직접적으로 컨트롤 할 수 없다(클라이언트가 DB에 접근 불가능하듯)

  • 어려웠던 말

    애플리케이션 상태는 클라이언트 측에서 관리하지만, 서버는 가능한 상태 전이를 나타내는 표현을 보내 조작할 수 있다

    • 애플리케이션 상태는 클라이언트측에서 관리한다.
    • 서버는 애플리케이션 상태를 모르기 때문이다.
    • 현재 보고있는 데이터가 무엇인지, 다음 수행할 수 있는 동작이 어떤것들인지는 클라이언트에서 기억하고 서버에 요청한다.
    • 요청을 받은 서버는 “어떤 상태로 전이되는지”를 보여준다(데이터가 추가되거나 삭제된 모습, 새로운 링크 등)
    • 하지만 그걸 받아 화면에 출력하는 것(실제 애플리케이션 상태의 변화)은 클라이언트의 몫이다.
    • 서버가 보낸 데이터에 따라 클라이언트가 하는 짓이 달라진다?
    • 서버가 말한대로 행동하니까
    • 서버가 조질라면 조질 수 있다.

연결

  • 연결의 원칙 : 각 페이지는 인접한 페이지에 어떻게 갈 수 있는지 알려준다(클릭, 입력 등등)
  • ‘애플리케이션 상태의 엔진으로서 하이퍼미디어’
    • 애플리케이션 상태를 변경할 수 있는 하이퍼미디어
    • 페이지를 변경할 수 있는 하이퍼미디어
  • 따라서 각 하이퍼미디어는 서버가 다음에 무엇을 할 수 있는지를 말해준다.
    • ex1. 입력폼은 서버가 리소스 상태를 추가할 수 있음을 알려준다.
    • ex2. 출력 태그는 서버가 리소스 상태를 조회할 수 있음을 알려준다.

웹보다 뒤쳐지는 웹 API

  • 자기 서술 메시지 원칙(Self-Descriptive Messages Principle) : 별도의 문서나 추가 데이터가 없어도, 응답 메시지만으로 작업과 영향에 대해 파악할 수 있어야 함.
  • 따라서 URL 이름을 잘 짓자

의미 체계(semantic)의 문제

  • 문서의 구조를 이해하는 것과 문서의 의미를 이해하는 것은 차이가 있다.
  • 자기 서술적 메시지를 파악하고 선택하는 것을 모두 인간이 수행하지 않고, 그럴 순 없다.
  • 이를 위해 웹 API 설계를 배워야 함

2장

HTTP GET: 확실한 시도

  • GET 요청 : 표현을 요청한다.
  • 서버의 리소스 상태를 변경할 의도가 전혀 없다 = 리소스의 URL만 알아도 요청을 보내고 표현을 받을 수 있다.
  • GET 요청은 안전해야 하고, 큰 부작용을 야기하도록 해선 안된다.

HTTP 응답 읽기

  • 상태 코드(status code) or 응답 코드(response code) : 요청의 결과를 요약하여 세 자리 숫자로 표현

  • 본문(body) or 엔티티-바디(entity-body) : 데이터가 담겨 있음

    정확히는, HTTP 응답 전체가 “표현”이고 본문안에는 중요한 정보가 들어있는 것임)

  • 응답헤더
    • 키-값 형태
    • Content-Type : 클라이언트가 바디를 어떻게 이해해햐 할지 설명해줌
      • 이 키의 값은 엔티티 바디의 미디어 유형(media type)이나 MIME 유형 등으로 부른다

JSON

  • 정확한 정의는 평문(plain-text)으로 간단한 자료구조를 표현하는 표준
  • 문자열(”큰 따옴표”), 리스트([대괄호]), 객체({”키-값 묶음은”: “중괄호”}) 를 알맞은 형식으로 표기함
  • 이것이 제공되기 위해선 Content-Type이 “application/json”이어야 함

Collection+JSON

  • JSON의 형식에 제약을 건 형태
  • Content-Type: application/vnd.collection+json 일 때
  • JSON이 정해진 표준대로 키-값 을 가져야 함
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# Collection+JSON의 예시
{
	"collection": 
		{
			"version" : "1.0",
			"href": "https://www.naver.com",
			"items": [
				{
					"href": "https://www.naver.com/news/1254215",
					"data": [
						{
							"name": "text",
							"value": "Test",
						},
						{
							"name": "skdqwkdq",
							"value": "hkrhklrhkrh",
						},
					],
					"links": [],
				},
			],
			...
}

각 키의 값으로는 정해진 대상이 들어가야 한다. 예를 들어, 4번째 줄 href는 “이 문서의 표현을 가져오는 데 사용한 주소”가 들어가야 한다. 즉, 이 리소스의 URL을 의미한다.

API 작성하기

  • Collection+JSON 표준으로 작성하려면
    1. 클라이언트가 template 객체를 사용해 유효한 표현을 작성하고
    2. HTTP POST를 사용해 이 1의 표현을 서버에 보내서
    3. 서버가 처리해야 한다.

HTTP POST: 리소스는 어떻게 탄생할까

  • 응답 코드 201을 받으면, 헤더의 Location에 생성된 것을 찾을 수 있는 곳을 알 수 있다.

제약 조건으로 자유해짐

  • RESTful 디자인을 따르면 제약이 많이 생긴다
  • 그러나 그 제약이 자유를 준다.
  • 언제 GET 요청을 보내도 아무 악영향이 없다는 확신이 생기기 때문.
  • JSON에 담기면 그 값의 의미를 알 수 있다.
  • Collection+JSON 으로 작성한다면?
    • 담긴 링크(href)의 의미를 알려줄 필요가 없음

애플리케이션 의미 체계가 의미적 차이를 만든다

  • Collection+JSON도 내부 항목을 커스텀할 수 있다.
  • 이렇게 개별적으로 변경되는 것들이 애플리케이션 의미 체계다.
  • 이게 바로 1장에서 말하는 의미 체계(semantic)의 문제.
CATALOG
    restful