![[HTTP/네트워크] 실습 (REST API, Postman)](https://img1.daumcdn.net/thumb/R750x0/?scode=mtistory2&fname=https%3A%2F%2Fblog.kakaocdn.net%2Fdn%2FbR4TpR%2Fbtq8cOTCHgj%2FqFmX8DYwAQ5Ar4NfpZGSe1%2Fimg.png)
CSR(Client Side Rendering)에서는 몇 가지의 메소드를 이용해 서버와 통신합니다. GET을 통해 웹 페이지나 데이터를 요청하고, POST로 새로운 글이나 데이터를 전송하거나 DELETE로 저장된 글이나 데이터를 삭제할 수 있습니다.
REST API에서 REST는 “Representational State Transfer”의 약자로, 웹(http)의 장점을 최대한 활용할 수 있는 아키텍처로써 처음 소개되었습니다.
REST API는 웹에서 사용되는 모든 자원을 HTTP URI로 표현하고, HTTP Method를 통해 요청과 응답을 정의하는 방식을 말합니다. REST API를 사용한다는 것은 REST 아키텍처의 제약 조건을 준수한다는 말입니다.
그리고 Postman은 앱으로 깔아서 쓰는게 편합니다.
REST API
1. Endpoint
http://3.36.72.17:3000
- root-endpoint(혹은 root-URL): API로 요청을 서버와 통신할 때, 서버가 요청을 수락하는 시작점을 뜻합니다.
Github API의 root-endpoint는 https://api.github.com이고, 트위터 API의 root-endpoint는 https://api.twitter.com입니다. 일반적으로 root-endpoint는 도메인 주소의 루트(/)를 가리킵니다. 마찬가지로 Message States Server 의 URL을 기준으로 파악할 수 있는 root-endpoint는 Message States Server의 가장 마지막 Location인 호스트의 루트(/)입니다.
- path: path(또는 url-path)는 API를 통해 서버와 통신할 때, 서버와 통신할 수 있는 key 역할을 합니다. 서버에 정의된 문자열에 따라 path가 달라집니다. 예를 들어, https://api.github.com/user 에서는 'user'가 path입니다.
2. 메시지 조회
Request
GET /{githubID}/messages -- githubID가 작성한 모든 메시지를 조회합니다.
{githubID} 부분은, 요청하는 사람의 아이디를 넣게되면 아래와 같습니다.
GET /kimcoding/messages -- kimcoding이 작성한 모든 메시지를 조회합니다.
이 요청에는 추가적인 파라미터(query parameter)를 사용할 수 있습니다. 파라미터는 다음과 같이 사용할 수 있습니다.
- /kimcoding/messages?roomname=로비
| parameter | 형식 | 형식 | 필수 포함 여부 |
| roomname | 방 이름(문자열) | 특정 roomname만 조회 | 필수 아님 |
[표] 파라미터 정보
Response
응답은 다음과 같은 JSON 형식입니다.
[
{
"id": 1,
"username": "김코딩",
"text": "안녕하세요",
"roomname": "로비",
"date": "2021-07-28T03:54:21.134"
},
// ...여러 개의 메시지
]
메시지에서 사용하는 속성은 다음과 같습니다.
| parameter | 형식 | 설명 |
| id | 숫자 | 고유한 아이디 |
| username | 문자열 | 사용자 이름 |
| text | 문자열 | 본문 내용 |
| roomname | 문자열 | 방 이름 |
| date | 문자열 | 작성한 시간 |
[표] 파라미터 정보
3. 메시지 추가
Request
POST /{githubID}/messages -- githubID가 작성한 메시지를 생성합니다.
{githubID} 부분은, 각 개인의 아이디를 넣습니다. 메시지는 24시간마다 자동으로 리셋됩니다.
요청 본문엔 다음 내용을 반드시 포함해야 합니다.
- 요청 형식: JSON
- MIME 타입: application/json
| parameter | 형식 | 설명 | 필수 포함 여부 |
| username | 문자열 | 사용자 이름 | 필수 |
| text | 문자열 | 본문 내용 | 필수 |
| roomname | 문자열 | 방 이름 | 필수 |
[표] 파라미터 정보
Response
응답은 다음과 같은 JSON 형식입니다.
{
"id": 5
}[데이터] Request에 따른 Response 예시
id는 숫자 형식이며, 새로 생성된 메시지의 고유한 ID값입니다.
4. 메시지 초기화
Request
POST /{githubID}/clear -- [요청] githubID가 작성한 메시지를 초기화합니다.
요청 본문은 필요하지 않습니다.
Response
응답은 JSON 형식입니다.
{
"message": "message initialized!"
}
Postman 사용하는 방법
HTTP API 테스트 도구
웹 개발에서 사용하는 대표적인 클라이언트는 브라우저입니다. 브라우저는 서버에 HTTP 요청을 보낼 수 있는 훌륭한 도구이지만, 주로 웹 페이지를 받아오는 GET 요청에 사용합니다. 브라우저의 주소창에 URL을 입력하면, 해당 URL의 root-endpoint로 GET 요청을 보냅니다. 테스트를 위해 GET이 아닌 다른 요청을 보내려면, 개발자 도구의 콘솔 창에서 내장 함수 fetch를 사용해야 합니다.
매번 코드를 작성할 수는 있습니다. 그러나 테스트를 위해 매번 코드를 작성하는 건 상당히 번거로운 작업입니다. 매번 코드를 작성하는 것 대신에, HTTP 요청을 테스트할 수 있는 다양한 도구가 있습니다. 많은 API가 HTTP 프로토콜을 이용하므로, API 테스트 도구라고 부릅니다. 이러한 API 테스트 도구는 클라이언트 입장에서 서버 API를 테스트하거나, API를 만드는 과정에서도 매우 유용합니다.
HTTP API 테스트 도구 (CLI)
- curl (대부분의 리눅스 환경에 내장되어 있습니다.)
- wuzz
HTTP API 테스트 도구 (GUI)
Postman 사용하기
먼저, 이미 만들어져 있는 API 서버가 주어지는 경우를 생각해보겠습니다. HTTP로 소통하기 위해서는 API 서버의 endpoint가 URL로 주어져야 합니다. 예를 들어, 다음과 같은 API 문서가 있다고 가정하겠습니다.
Postman 화면 보기
다음 그림을 보고 포스트맨의 화면 구성을 확인합니다.
- 새로운 탭 오픈
- 요청/응답을 여러 개 확인할 수 있습니다.
- HTTP 메소드 선택
- GET, POST, DELETE 등과 같은 메소드 중 하나를 선택합니다.
- API 문서 상 GET 메소드를 사용하므로, GET으로 선택합니다.
- GET, POST, DELETE 등과 같은 메소드 중 하나를 선택합니다.
- URL 입력 창
- URL과 Endpoint를 입력합니다.
- API 문서에 따르면, http://3.36.72.17:3000/kimcoding/messages 과 같이 입력하면 됩니다.
- URL과 Endpoint를 입력합니다.
- HTTP 요청 버튼
- 요청을 보냅니다.
- HTTP 요청시 설정할 수 있는 각종 옵션
- 추가적인 파라미터나, 요청 본문(body)을 추가할 수 있습니다.
- API 문서에서 확인할 수 있듯이, roomname 이라는 파라미터를 사용할 수 있습니다. 필수는 아니지만, 파라미터를 사용하려면 Params 탭의 KEY, VALUE 에 각각 roomname 과 필요한 값을 입력합니다.
- 추가적인 파라미터나, 요청 본문(body)을 추가할 수 있습니다.
- HTTP 응답 화면
- 요청을 보낸 후 응답을 확인하세요.
POST 요청하기
POST 요청은 GET 요청과 다르게 본문(body)를 포함하는 경우가 많습니다.
- 본문의 형식 선택 (1)
- JSON 형식으로 보낼 때에는, raw를 선택합니다.
- 본문의 형식 선택 (2)
- 보낼 형식에 맞게 정확한 타입을 선택합니다.
- JSON 형식으로 보낼 때에는, JSON을 선택합니다.
- 앞서 1번 및 2번 과정은 HTTP 요청 헤더에 다음과 같이 작성하는 것과 동일합니다.
- 보낼 형식에 맞게 정확한 타입을 선택합니다.
- 본문 내용
- 본문을 입력합니다. 앞서 JSON을 선택했으므로, 유효한 JSON을 적어주어야 합니다.
- API 문서에 따르면 username, text, roomname 을 형식에 맞게 적어주어야 합니다.
- 본문을 입력합니다. 앞서 JSON을 선택했으므로, 유효한 JSON을 적어주어야 합니다.
모든 요청 본문 입력이 완료되었다면, 요청을 보냅니다. URL과 Endpoint, 그리고 HTTP 메소드를 정확하게 입력했는지 확인
응답 살펴보기
요청이 끝나지 않을 때
일반적으로 서버가 요청에 대한 응답을 하지않는 경우, 요청이 끝나지 않습니다. 이것은 서버의 문제입니다. 만약 여러분이 서버를 만드는 중이라면, 응답 처리를 했는지 확인합니다. 이 경우에는 timeout이라는 응답을 받게 됩니다.
기대했던 응답이 나오지 않을 때
결과에 아무것도 나오지 않거나, 기대했던 값이 나오지 않으면 HTTP 응답 코드를 확인
위 그림의 우측 상단에 HTTP 응답 코드가 표시됩니다. 400 Bad Request라고 되어 있다면, 잘못된 요청을 한 경우입니다.
무엇이든지 결과가 나왔다면, 그 결과를 잘 읽어보세요. 문제 해결의 실마리를 찾을 수 있습니다.
Postman으로 API 테스팅하기
Getting Started
1. 가입 및 설치
Postman에 회원가입을 한 후, 프로그램을 설치합니다.
2. 환경 설정
- Postman을 설치하면 다음과 같은 환경을 마주하게 됩니다. Workspaces에서 My Workspace를 클릭한 후 +를 눌러 테스팅을 시작합니다. 기존에 사용한 적이 있거나, 3번째 이미지로 시작된다면 바로 테스트를 시작하세요.
[그림] POSTMAN 실행화면 1
[그림] POSTMAN 실행화면 2
[그림] POSTMAN 실행화면 3
3. 테스팅 시작
- Postman을 활용하여 HTTP 요청을 합니다.
Postman으로 날씨 받아오기
Postman with Open API
- Open Weather Map의 API Docs를 보고 Open API를 사용하여 서울(혹은 거주 지역)의 날씨를 요청하고, 응답을 확인합니다.
Getting Started
1. 접속
- 먼저 https://openweathermap.org/ 에 접속합니다.
2. 로그인
- 로그인합니다.
- 아이디가 없다면, 회원가입 후 로그인합니다.
3. 인증
- 회원가입 후 메일 주소로 인증 메일을 받고, 인증 절차를 진행합니다.
4. API 발급
- 로그인 후에 다음과 같이 API Keys 탭을 누르시면 기본 Default API 키가 발급된 것을 확인할 수 있습니다.
위 그림에서 확인할 수 있는 API Key는 OpenWeather에서 기본으로 제공합니다.
추가로 키를 발급하고 싶다면 Create key 에 새로 발급할 API Key 이름을 추가해 Generate 을 누르면 됩니다.
5. 원하는 API 탐색
- 상단 내비게이션 바의 API 를 클릭하면, 사용할 수 있는 API 리스트를 확인할 수 있습니다.
Current Weather Data 카드에 있는 API Doc 을 눌러 문서를 확인할 수 있습니다.
'By city ID' 라는 소제목의 글을 보면, 다음과 같이 uri를 확인할 수 있습니다.
api.openweathermap.org/data/2.5/weather?id={city id}&appid={your api key}[요청] 'By city ID'에서는 URI를 제공합니다.
주어진 uri와 발급받은 API 키로 날씨 데이터에 접근할 수 있습니다. 중괄호 안에 있는 city id 에는 OpenWeather에서 도시마다 부여한 ID 중 하나를 입력할 수 있습니다. your api key 에는 발급받은 API Key를 입력합니다. 서울의 city id 는 1835848 입니다.
6. API 호출
6.1. URI로 확인
데이터를 정상적으로 받아올 수 있는지, uri 는 작동을 하는지 확인하기 위해 브라우저에 다음과 같이 입력합니다.
api.openweathermap.org/data/2.5/weather?id=1835848&appid={your api key}[요청] 'city id'에 서울의 id를, 'your api key'에 발급받은 api key를 입력하고, 브라우저의 검색창에 입력합니다.
다음과 같은 결과가 나타난다면, 데이터를 잘 받고 있는 겁니다.
브라우저에서 JSON 형식의 데이터를 정리해서 보여주는 기능을 사용하면, 다음과 같이 구조적으로 데이터를 확인할 수 있습니다. 여기에서 사용된 기능 이름은 JSON Viewer 입니다.
6.2. Postman으로 확인
- Postman으로 날씨 데이터를 받아옵니다. URI로 확인한 데이터와 같으면 성공입니다.
-----------------------------------------------------------------------------------------------
REST API는 어떻게 디자인해야 하는가
REST API는 공식적으로 정해진 뚜렷한 규격이 없습니다. 그렇다 보니, 개발자에 따라 REST API 특징(원칙)에 맞춰 조금씩 다른 모습을 하고 있습니다. 그러나 REST API 모범 사례는 여전히 논의되고 통합되고 있기 때문에, 수많은 디자인 중에 분명히 보기 좋은 REST API 디자인은 있습니다. 다음의 API 작성 가이드를 참고한다면, 모범적인 API 디자인에 가깝게 코드를 작성할 수 있습니다.
API 작성 가이드를 모두 읽었다면, REST API 설계시 가장 중요한 두 가지를 이해할 수 있습니다.
- URI는 정보의 자원을 표현합니다.
- 자원에 대한 상태 정의는 HTTP method(GET, POST, PUT, DELETE...)로 표현합니다.
예를 들어, GET /user/1122/post라는 URI는 REST API에 부합하지 않습니다. POST /user/1122처럼 표현하는 것이 REST API 규칙에 부합합니다.
Open API와 API Key
Open API
정부에서 제공하는 공공데이터가 있습니다. 공공데이터에 쉽게 접근할 수 있도록 정부는 Open API의 형태로 공공데이터를 제공하고 있습니다. 공공데이터포털에 접속해 원하는 키워드를 검색하면, 해당 키워드와 관련된 API를 확인할 수 있습니다.
이 API에는 "Open"이라는 키워드가 붙어 있습니다. 글자 그대로 누구에게나 열려있는 API입니다. 그러나 "무제한으로 이용할 수 있다"는 의미는 아닙니다. 기관이나 API마다 정해진 이용 수칙이 있고, 그 이용 수칙에 따라 제한사항(가격, 정보의 제한 등)이 있을 수 있습니다.
Open API를 간단하게 경험해 볼 수 있는 대표적인 페이지는, Open Weather Map이라는 웹 사이트에서 제공하는 날씨 API 입니다. 이 웹사이트에서는 다음의 설명처럼 데이터를 제공합니다.
- 제한적이나마 무료로 날씨 API를 사용할 수 있습니다.
- 프리 플랜에서는 기본적으로 분당 60번, 달마다 1백 번 호출이 가능합니다.
- 데이터를 JSON 형태로 응답합니다.
API Key
API를 이용하기 위해서는 API Key가 필요합니다. API key는 서버의 문을 여는 열쇠라고 생각할 수 있습니다. 클라이언트의 요청에 따라 서버에서 응답한다는 말은 결국 서버를 운용하는 데에 비용이 발생한다는 말입니다. 따라서 서버 입장에서 아무런 조건 없이 익명의 클라이언트에게 데이터를 제공할 의무도, 이유도 없습니다. (가끔 API key가 필요하지 않은 경우도 있습니다.)
그래서 로그인된 이용자에게만 자원에 접근할 수 있는 권한을 API Key의 형태로 제공하고, 데이터를 요청할 때 API key를 같이 전달해야만 원하는 응답을 받을 수 있습니다.
'Computer Science > Server, 네트워크' 카테고리의 다른 글
| [Server] OAuth 2.0 (0) | 2021.08.04 |
|---|---|
| [Server] 보안 인증 (Token-JWT) (0) | 2021.08.03 |
| [Server] 보안 인증 기초 (HTTPS/Hashing/cookie/CSRF) (0) | 2021.08.02 |
| [Web Server] 기초 (0) | 2021.07.01 |
| [HTTP/네트워크] 기초 (4) | 2021.06.24 |