10장 REST API와 JSON

10.1 REST API와 JSON의 등장 배경

웹 서비스를 사용하는 클라이언트에는 웹 브라우저만 있는 게 아닙니다. 스마트폰, 스마트워치, 태블릿, CCTV, 각종 센서 등이 모두 클라이언트입니다. IT 기기의 발전에 따라 지금도 수많은 클라이언트가 만들어지고 있습니다.

 

서버는 이러한 모든 클라이언트의 요청에 응답해야 합니다. 웹 브라우저뿐만 아니라 어떤 기기가 와도 기기에 맞는 뷰 페이지(view1, view2, ...)를 응답해야 합니다.

 

그런데 이런 기기들은 앞으로 끝없이 나올텐데 그때마다 서버가 일일이 대응하기란 쉽지 않습니다. 이때 바로 REST API를 사용하는 것입니다.

 

REST API(Representational State Transfer API)는 서버의 자원을 클라이언트에 구애받지 않고 사용할 수 있게 하는 설계 방식입니다. REST API 방식에서는 HTTP 요청에 대한 응답으로 서버의 자원을 반환합니다. 서버에서 보내는 응답이 특정 기기에 종속되지 않도록 모든 기기에서 통용될 수 있는 데이터를 반환합니다.

 

다음 그림은 REST API의 동작을 나타냅니다. 서버는 클라이언트의 요청에 대한 응답으로 화면(view)이 아닌 데이터(data)를 전송합니다. 이때 사용하는 응답 데이터는 JSON(JavaScript Object Notation)입니다. 과거에는 응답 데이터로 XML을 많이 사용했지만, 최근에는 JSON으로 통일되는 추세입니다.

 

API

API(Application Programming Interface)란 애플리케이션을 간편히 사용할 수 있게 하는, 미리 정해진 일종의 약속으로, 사용자와 프로그램 간 상호작용을 돕습니다. 자판기를 예로 들면, 자판기 버튼이 하나의 API가 됩니다. 콜라 버튼을 누르면 콜라가, 사이다 버튼을 누르면 사이다가 나오는 것은 각 버튼에 따라 반환될 음료를 미리 약속했기 때문입니다. 이와 마찬가지로 '윈도우 API'는 윈도우 개발을 위해 미리 정해진 약속, '자바 API'는 자바 개발을 위해 미리 만들어진 약속이라고 보면 됩니다. 

 

XML과 JSON의 데이터 형식을 간단히 비교하면 다음과 같습니다. XML은 사용자 정의형 HTML 정도로 볼 수 있고, JSON은 자바스크립트 방식을 차용한 객체 표현식 정도로 볼 수 있습니다.

//XML : Extensible Markup Language
<article-form>
    <id>1</id>
    <title>가가가가</title>
    <content>1111</content>
</article-form>

//JSON : JavaScript Object Notation
{
    "id": 1,
    "title": "가가가가",
    "content": "1111"
}

 

JSON 데이터는 키(key)와 값(value)으로 구성된 정렬되지 않은 속성(property)의 집합입니다. 키는 문자열이므로 항상 큰따옴표("") 로 감싸고, 값은 문자열인 경우에만 큰따옴표("")로 감쌉니다. 예를 들어, 3개의 속성을 가진 강아지 객체를 JSON 데이터로 표현하면 다음과 같습니다.

{
    "name": "망고",
    "breeds": "골든리트리버",
    "age": 2
}

---

10.2 REST API 동작 살펴보기

이 절에서는 연습용 REST API 서버에 접속해서 HTTP 요청과 응답을 실습합니다. 연습용 REST API 서버는 {JSON} Placeholder 사이트에 가면 사용할 수 있습니다.

 

10.2.1 {JSON} Placeholder 사이트 둘러보기

{JSON} Placeholder 사이트(https://jsonplaceholder.typicode.com/)에 접속합니다. 이 사이트는 가짜(fake) API를 사용해 무료로 각종 테스트를 진행할 수 있는 서비스를 제공합니다.

 

- 사이트 사용 방법

스크롤을 내리면 Try it이 보입니다. 이 부분에 HTTP 요청 코드가 작성되어 있습니다. [Run script] 버튼을 클릭하면 그에 대한 응답으로 JSON 데이터를 확인할 수 있습니다.

 

- 사이트에서 제공하는 자원

스크롤을 좀 더 내리면 Resources가 보입니다. 여기서는 가짜 더미 데이터로 HTTP 요청을 보내고 응답 결과를 확인할 수 있습니다. 사이트에서 제공하는 자원(resources)은 게시글(posts) 100개, 댓글(comments) 500개, 앨범(albums) 100개, 사진(photos) 5,000개, 할 일 목록(todos) 200개, 사용자(users) 10명입니다.

 

- HTTP 메서드와 URL 경로

스크롤을 더 내리면 Routes가 보입니다. 7장에서 데이터를 생성, 조회, 수정, 삭제하려면 HTTP 메서드로 요청을 보내야 한다고 배웠습니다. REST API는 모든 HTTP 메서드를 지원합니다. Routes를 보면 이 사이트에서 메서드별로 요청을 보낼 때 사용하는 URL 경로가 나와있습니다. 이 URL 경로를 어떻게 활용하는지 구체적인 예를 보겠습니다. Note에 있는 guide를 클릭하세요.

 

- REST API 사용 예

guide를 클릭하면 페이지가 바뀌면서 첫 번째로 단일 데이터를 조회하는 예가 나옵니다. URL 경로가 'https://.../posts/1'이니 1번 게시글을 조회하는 요청입니다. 바로 아래 출력 결과(Output)를 보면 1번 게시글의 id, title, body, userId가 응답됐습니다. 이때 데이터의 형태는 JSON입니다.

 

그런데 이상한 점이 있습니다. 데이터 조회를 요청할 때는 method의 속성 값으로 GET을 써야 하는데 GET이 없습니다. 왜 그럴까요? GET은 method 속성의 기본값이므로 이 경우 생략해도 됩니다.

 

아래는 모든 데이터를 조회하는 예입니다. 이 역시 GET 요청이어서 method 속성을 따로 표기하지 않았습니다. 그리고 URL 경로는 'https://.../posts'입니다. 모든 게시글을 조회해 보여 달라는 뜻입니다. 결과를 보면 1부터 100까지 모든 게시글이 JSON 데이터로 반환된 것을 볼 수 있습니다.

 

아래는 새 게시글을 등록하는 예입니다. 이데이터 생성 요청이므로 method의 속성 값은 POST입니다. URL 경로는 'https://.../posts'입니다. 요청의 body 부분을 보면 JSON 데이터로 새 게시글의 title, body, userId 값도 같이 보낸 것을 확인할 수 있습니다.

 

여기서는 POST 메서드를 통해 지정된 URL로 요청을 보내면 게시판에 새 글이 등록되고 새로 생성된 데이터는 JSON 형태로 반환된다는 사실만 기억하면 됩니다.

 

아래는 게시글을 수정하는 예입니다. 데이터 수정 요청이므로 method의 속성 값은 PUT과 PATCH를 썼습니다. 요청 URL 경로는 둘 다 'https://.../posts/1'이므로 1번 게시글의 수정 요청임을 알 수 있습니다.

이때 PUT과 PATCH의 차이점은 다음과 같습니다.

- PUT : 기존 데이터를 전부 새 내용으로 변경합니다. 만약 기존 데이터가 없다면 새로 생성합니다.

- PATCH : 기존 데이터 중에서 일부만 새 내용으로 변경합니다.

 

PUT 예시를 보면 1번 데이터의 속성을 모두 수정 요청했고, PATCH 예시를 보면 1번 데이터의 title만 수정 요청했습니다.

 

마지막은 게시글을 삭제하는 예입니다. 데이터 삭제 요청이므로 method의 속성 값으로 DELETE를 썼습니다. 요청 URL은 'https://.../posts/1'이니 1번 게시글을 삭제하는것입니다.

 

10.2.2 Talend API Tester 설치하기

크롭 웹 브라우저에 Talend API Tester 라는 확장 프로그램을 설치하겠습니다.

 

1. 구글 검색창에 talend api 확장 프로그램을 검색합니다. 크롬 웹 스토어의 Talend API Tester가 검색됩니다. 해당 링크를 클릭합니다.

 

2. 크롬 웹 스토어의 Talend API Tester 설치 화면이 나옵니다. [Chrome에 추가] 버튼을 클릭한 후 확인 창이 뜨면 [확장 프로그램 추가] 버튼을 클릭합니다.

 

3. 크롬 브라우저 오른쪽 상단에 퍼즐 모양의 아이콘을 클릭하면 현재 설치된 확장 프로그램 목록이 나옵니다. 여기서 Talend API Tester 프로그램의 핀 아이콘을 활성화해 바로 가기 아이콘을 생성합니다.

 

4. Talend API Tester 아이콘을 클릭합니다. 화면 가운데 [Use Talend API Tester - Free Edition] 버튼을 클릭해 프로그램을 시작합니다. 

 

이제 Talend API Tester 프로그램을 이용해 HTTP 요청을 보내고 돌아온 응답을 확인할 수 있습니다. {JSON} Placeholder 사이트에서 확인한 게시글, 댓글, 앨범 등의 자원을 JSON 형식으로 받아 오는 예제를 실습해 보겠습니다.

 

10.2.3 Get 요청하고 응답받기

1. 모든 게시글을 조회해 보겠습니다. Talend API Tester에서 메서드는 GET을 선택합니다. 모든 데이터를 조회할 때 URL 경로는 'https://.../posts'였습니다. 따라서 URL에는 https://jsonplaceholder.typicode.com/posts를 입력합니다. 작성한 URL 경로로 모든 데이터를 조회하라는 요청입니다. [Send] 버튼을 클릭해 봅시다.

 

2. 응답(Response)이 200으로 왔습니다. 200은 요청이 잘 처리됐다는 것을 의미하는 상태 코드입니다. BODY 부분을 보면 응답으로 온 1번부터 100번까지 게시글의 JSON 데이터를 확인할 수 있습니다.

 

3. 1번 게시글을 조회해 보겠습니다. GET 요청은 그대로 두고 URL 마지막에 /1을 추가해 https://jsonplaceholder.typicode.com/posts/1로 수정합니다. [Send] 버튼을 클릭하면 상태 코드 200이 응답으로 옵니다. BODY에는 1번 아이디를 가진 게시글의 JSON 데이터를 확인할 수 있습니다.

 

4. 이번에는 데이터 조회 요청을 실패해 봅시다. 게시글은 100번까지 있습니다. URL을  https://jsonplaceholder.typicode.com/posts/101로 수정하고 [Send] 버튼을 클릭해 봅시다. 응답으로 404 에러가 뜹니다. 상태 코드 404는 요청한 페이지를 찾을 수 없다(not found)는 의미입니다.

 

{JSON} Placeholder 사이트에서 제공하는 게시글은 총 100개입니다. 그런데 101번을 요청했기 때문에 해당 게시글을 찾을 수 없어서 404 에러가 떴습니다. 응답의 BODY를 보면 데이터 없이 텅텅 비어 있는 것({})을 확인할 수 있습니다.

 

- HTTP 상태 코드

HTTP 상태 코드는 클라이언트가 보낸 요청이 성공했는지, 실패했는지 알려 주는 코드입니다.  코드는 100번대부터 500번대까지 5개 그룹으로 나뉘어 있습니다.

상태 코드	설명
1XX(정보)	요청이 수신돼 처리 중입니다.
2XX(성공)	요청이 정상적으로 처리됐습니다.
3XX(리다이렉션 메시지)	요청을 완료하려면 추가 행동이 필요합니다.
4XX(클라이언트 요청 오류)	클라이언트의 요청이  잘못돼 서버가 요청을 수행할 수 없습니다.
5XX(서버 응답 오류)	서버 내부에 에러가 발생해 클라이언트 요청에 대해 적절히 수행하지 못했습니다.

 

- HTTP 요청 메시지와 응답 메시지

앞에서 GET 메서드로 데이터 조회를 요청하고 성공한 응답과 실패한 응답을 받아 봤습니다.

실제로 이러한 요청과 응답은 HTTP 메시지에 실려 전송됩니다. HTTP 메시지는 Talend API Tester 화면 아래에 [HTTP] 탭을 클릭하면 볼 수 있습니다.

 

HTTP 메시지는 시작 라인(start line), 헤더(header), 빈 라인(blank line), 본문(body)으로 구성됩니다.

- 시작 라인 : HTTP 요청 또는 응답 내용이 있습니다. 시작 라인은 항상 한 줄로 끝납니다.

- 헤더 : HTTP 전송에 필요한 부가 정보가 있습니다.

- 빈 라인 : 헤더의 끝을 알리는 빈 줄로, 헤더가 모두 전송되었음을 알립니다.

- 본문 : 실제 전송하는 데이터가 있습니다.

 

맨 위에 HTTP 요청 메시지부터 보겠습니다. 요청 메시지의 시작 라인에는 요청의 종류(GET), URL 경로(/posts/101), 사용하는 HTTP 버전(HTTP/1.1)이 있고 헤더에는 호스트 주소(jsonplaceholder.typicode.com, 어디로 보낼지에 대한 정보)가 있습니다. 헤더 부분은 쉽게 말해 편지 봉투와 같습니다.

 

그 아래 응답 메시지도 보겠습니다. 응답 메시지의 시작 라인에는 HTTP 버전(HTTP/1.1)과 상태 코드(404)가 있습니다. 상태 코드가 404이므로 페이지를 찾을 수 없다는 내용입니다. 그리고 헤더에는 응답을 보낸 날짜(data), 응답 데이터 형식(content-type) 등이 있습니다.

 

응답 메시지의 헤더 아래에 한 줄 띄고 그 다음은 본문입니다. 본문에는 메시지에 실어 보내는 실제 데이터가 있습니다. 헤더가 편지 봉투였다면 본문은 편지 내용과 같습니다. 앞서 /posts/101을 요청해서 404 에러가 났으므로 본문은 비어({}) 있습니다.

 

이와 같이 HTTP 요청과 응답을 보내면 실제 HTTP 메시지로 변환돼 전송됩니다.

 

10.2.4 POST 요청하고 응답받기

1. 메서드를 POST로 선택하고 URL은 https://jsonplaceholder.typicode.com/posts로 수정합니다. 그리고 BODY 부분에 다음과 같이 JSON 형식의 데이터를 입력한 후 [Send] 버튼을 클릭합니다.

 

2. 응답으로 201이 옵니다. 상태 코드 201은 데이터가 잘 생성됐음을 의미합니다. BODY 부분을 보면 새로 생성된 데이터가 JSON 형식으로 잘 반환됐습니다.

 

실제 HTTP 메시지를 볼까요? [HTTP] 탭을 확인해 보면 요청 메시지의 시작 라인과 헤더에는 각종 정보가, 본문에는 새로 생성할 데이터가 있습니다.

 

응답 메시지도 시작 라인과 헤더에는 응답 정보가, 본문에는 생성 데이터가 실려 반환됐습니다. 이때 id는 자동으로 101번이 매겨졌습니다.

 

3. 데이터 생성 요청이 실패했을 때 어떤 응답이 오는지 확인해 보겠습니다. 데이터 생성을 요청 할 때 BODY에 JSON 데이터를 잘못 표기해 보겠습니다. title과 body에 큰 따옴표를 지우고 [Send] 버튼을 클릭합니다.

 

4. 응답이 500이 옵니다. 상태 코드 500은 서버 내부에 에러가 발생했다는 것을 의미합니다. 응답의 BODY를 보면 'SyntaxError: ...'라고 나옵니다. 요청을 보낼 때 JSON 데이털르 잘못 보내면 이런 문제가 발생합니다.

 

이 내용을 [HTTP] 탭에서도 확인할 수 있습니다. HTTP 요청 메시지를 보면 JSON 데이터의 title과 body 속성에 큰 따옴표가 빠져 있습니다.

 

HTTP 응답 메시지의 시작 라인에는 서버에 문제가 생겼음을 의미하는 상태 코드 500이 보이고, 본문에는 에러가 났음을 알리는 내용들이 적혀 있습니다.

 

10.2.5PATCH 요청하고 응답받기

1. 수정 요청을 보내려면 PUT이나 PATCH 메서드를 사용하는데, 여기서는 PATCH 메서드를 사용하겠습니다. URL은 1번 게시글을 수정하도록 https://jsonplaceholder.typicode.com/posts/1로 작성합니다. 수정할 내용은 BODY에 실어 보내야 하므로 title과 body를 다음과 같이 수정합니다. JSON 형식에 맞춰야 하므로 속성에 큰 따옴표를 붙여야합니다. [Send] 버튼을 클릭합니다.

 

2. 응답으로 200이 왔습니다. BODY를 보면 수정한 내용이 반환된 것을 확인할 수 있습니다.

 

10.2.5DELETE 요청하고 응답받기

1. 메서드를 DELETE로 설정하고 URL을 https://jsonplaceholder.typicode.com/posts/10으로 수정해 10번 게시글을 삭제해 보겠습니다. [Send] 버튼을 클릭합니다.

 

응답으로 200이 오면 잘 삭제됐다는 의미입니다.

 

HTTP 요청 메시지를 보면 DELETE로 10번 게시글 삭제를 요청했습니다. 응답 메시지의 시작 라인에는 잘 삭제됐다는 상태 코드 200이 있고, 본문에는 JSON 데이터의 중괄호({})가 텅텅 비어 있습니다.