230201 - REST API 복습, Postman 사용하기

1. REST API 복습

REST API

: 클라이언트와 서버가 데이터를 주고받을때는 HTTP를 사용한다. 이때 요청과 응답을 더 명확하게 하기 위해서 REST API를 사용한다. 

 

REST 성숙도 모델

• 0단계 : HTTP 프로토콜 사용
• 1단계 : 개별 리소스에 알맞은 엔드포인트 사용하고 요청하고 받는 리소스에 대한 정보를 응답으로 전달하기
• 2단계 : CRUD에 맞게 적절한 HTTP 메서드 사용하기. 응답시에는 성공/실패에 대한 상태코드를 정확히 알려주고 정확한 응답을 해주어야함.
  • GET 요청시에는 body를 사용하지 않는다. 더 정확하게 요청할때는 쿼리를 사용함. GET은 단순 조회로 여러번 요청해도 리소스가 변하지 않는다(=같은 리소스를 반환한다) => GET은 멱등성을 갖고 있다.
  • POST의 경우 요청시 새로운 리소스를 생성한다. 즉 요청시 리소스가 변한다. => 멱등하지 않다. 
  • PUT은 전체를 수정하고 PATCH는 부분을 수정한다. PATCH는 요청시마다 일부분이 계속 변경됨으로 멱등성이 없다. 토글이나 스위치같이 계속 상태가 변한다고 생각하면 된다. 따라서 PUT은 멱등하고 PATCH는 멱등하지 않다. 

 

REST API 작성 가이드라인

주소(엔드포인트) 작성시

동사, HTTP 메서드, 또는 어떤 행위에 관련된 이름으로 작성하는 것이 아니라 리소스에 집중한다. 즉 어떤 데이터를 가져오는지 고민하고 해당되는 명사형의 단어로 작성해야한다. 중복되는 단어는 사용하지 않는다. 

 

예시) 회원 정보 가져오는 URI
GET   /users/get1234 X (HTTP 메서드인 GET과 중복된다)
GET   /users/1234

 

URI 작성시

가급적 spinal-Case 형태로 작성하는 것을 권장한다. 반드시 이 형태로 해야 하는것은 아니다! 다만 언더바(_)는 가독성이 좋지 않거나 글꼴에 따라 문자가 가려질수도 있기때문에 언더바 대신 하이픈(-)사용을 권장한다. 

 

HTTP 메서드

• GET : 조회(READ). body 사용하지 않음
  http://abcd.com/hello-wolrd
• HEAD : status line, header만 조회한다
• POST : 생성(CREATE). body 사용함
  http://abcd.com/users
  body: {username: "harry"}
• PUT : 갱신(UPDATE). 해당 리소스를 완전히 바꿈. body 사용함
• PATCH : 갱신(UPDATE). 해당 리소스를 일부분만 바꿈. body 사용함
• DELETE : 삭제(DELETE). 해당 리소스 삭제함 

 

HTTP headers

• General Header : 요청 및 응답 메시지 모두에서 사용 가능한 기본적인 헤더 항목
• Client Request Header : 일반적인 요청 헤더
• Server Response Header : 일반적인 응답 헤더
• Entity Header : 요정 및 응답 메시지 모두에서 사용 가능한 Entity(콘텐츠, 본문, 리소스 등)에 대한 설명 헤더 항목
  ex) Content-Type(응답하는 데이터의 형식), Content-Length(body로 전달된 데이터의 길이) 등

 

Query parameters 예시

• Paging : ?page=1&per_page=30 (페이지네이션 구현시)
• Filtering : ?status=open
• Sorting : ?direction=desc(역순)
• Searching : ?q=javascript

 

주요 HTTP 상태코드

• 200 OK : GET 요청이 성공함. body로 리소스를 보내준다. 
• 201 Created: POST 요청이 성공함
• 204 No Content : DELETE 요청이 성공함. body에 리소스를 보내주지 않는다. 

 

• 304 Not Modified
  반복된 요청이 발생함(이미 원하는 데이터를 가지고 있음을 알려줌) GET 요청시 나타난다. 브라우저의 캐시 저장소에 해당 리소스가 있기 때문에 요청된 리소스를 재전송할 필요가 없음을 나타낸다. 

 

• 400 Bad Request : 잘못된 요청
• 401 Unauthorized : 인증되지 않음(예 : 로그인 안함)
• 403 Forbidden : 인증되었으나 권한이 없음(예: 로그인은 했는데 해당 기능을 수행할 권한이 없음)
• 404 Not Found : 해당 리소스 없음

 

• 500 Internal Server Error : 서버 오류

 

 

REST API 작성 예시

=> 유저 정보에 대한 API를 작성한다고 가정한다.

 

전체 유저 정보를 조회할때 

GET /users

성공 : 200 OK / 실패 : 400 Bad Request, 404 Not Found

 

개별 유저 정보를 조회할때

GET /users/123 (id 등으로 특정 유저를 지정)

성공 : 200 OK / 실패 : 400 Bad Request, 404 Not Found

 

새로운 유저를 추가할때

POST /users

body : {username : "harry", ...} 

성공 : 201 Created / 실패 : 400 Bad Request, 409 Conflict

 

개별 유저의 정보를 갱신할때

PUT /users/123

성공 : 200 OK, 204 No Content(되도록 200 권장) / 실패 : 400 Bad Request, 404 Not Found

 

PATCH /users/123

성공 : 201 Created / 실패 : 400 Bad Request, 404 Not Found

 

개별 유저를 삭제할때 

DELETE /users/123

성공 : 204 No Content, 200 OK / 실패 : 400 Bad Request, 404 Not Found

 

 

 

 

2. Postman

브라우저에서 보내는 HTTP 요청은 주로 웹페이지를 받아오는 GET 요청이다. API 테스트를 위해 다른 메서드를 사용한 요청을 보내기 위해서는 개발자도구의 콘솔창으로 fetch API를 사용해야한다. 하지만 매번 테스트를 위해 코드를 작성하는것은 번거롭기때문에 많은 개발자들은 API 테스트 도구들을 사용한다. 

 

🛠 HTTP API 테스트 도구

• CLI
  • curl(대부분의 리눅스 환경에 내장됨)
  • wuzz 
• GUI
  • Postman
  • Insomnia

 

Postman은 HTTP 요청을 테스트 할 수 있는 API 테스트 도구들 중 하나이다. API 테스트 도구는 클라이언트 입장에서 서버 API를 테스트 하거나 API를 만들때 유용하게 사용할 수 있다. 

 

 

1) 사용법

(1) 기본 설정

 

Postman 에 들어가 회원가입을 하고 프로그램을 설치하고 [Workspaces] - [My Workspace]로 이동한다.

[Workspaces] - [My Workspace]

 

 

 

 

+ 버튼을 클릭해 테스트를 실행할 워크스페이스를 추가한다.

+ 클릭

 

 

 

아래의 화면이 나오면 테스트를 시작할 수 있다. 

 

 

 

 

(2) 화면 구성

 

• HTTP 요청시 사용하는 옵션
  • Params : QueryString으로 요청 파라미터 설정
  • Authorization : API 인증을 위해 OAuth 2.0 / API Key / Bearer Token 지원
  • Headers : 요청 헤더에 정보 설정
  • Body : 데이터 타입 요청 파라미터 설정
    • form-data : 웹 페이지의 form 태그의 정보. Key-Value 조합으로 작성하며 파일 전송도 가능함.
    • x-www-form-unlencoded : form-data 형식과 같으나 영문자를 제외한 글자는 모두 인코딩한다. key-value 조합으로 작성하며 텍스트 타입 전송만 가능하다. 파일 전송은 불가능하다. 
    • raw : 파라미터 형식과 내용을 직접 작성하는 경우 선택한다. Text, JavaScript, JSON, HTML, XML이 있다. 
    • binary : 파일 전송시 사용한다.
  • Pre-request script : 요청을 보내기 전 특정 스크립트를 작성하여 미리 만들어 놓은 요청들을 순서대로 실행하는 시나리오 실행 가능 

 

 

 

(3) 요청 방법

무료 온라인 REST API 사이트인 JSONPlaceholder를 사용해서 GET 요청과 POST 요청을 연습해보기로 했다. 

https://jsonplaceholder.typicode.com/

JSONPlaceholder - Free Fake REST API

 

GET

/user의 모든 정보를 가져와보기로 했다. 

 

정보를 읽어올것이기때문에 GET 메서드를 사용하도록 설정하고, 인풋에 API 서버의 endpoint를 URL로 적어준다. 

 

https://jsonplaceholder.typicode.com/users

 

 

이렇게 입력하면 해당 API 서버의 endpoint /users의 정보를 요청하는 내용이 된다. 

 

 

요청을 보내면 오른쪽 상단에서 200 OK 라는 상태코드를 확인할 수 있다. 요청이 성공했다는 뜻이다. 

아래 영역에서 응답의 본문도 확인할 수 있다. 

 

 

파라미터를 사용해 특정한 리소스만 요청하고싶다면 Params에 KEY와 VALUE를 입력해 주면 된다. 

이번에는 username이 Kamren인 유저의 정보만 가져와보겠다. 

이럴때는 아래와 같이 입력해주면 해당하는 유저의 정보만 응답받을 수 있다. 

 

 

 

 

 

 

POST

/user에 새로운 유저를 추가할 것이다. 

POST 메서드를 사용하고, 필요한 데이터는 우선 JSON 형식으로 직접 입력할 것이다. 

JSON 형식으로 직접 입력할때는 Body 메뉴에서 raw 옵션을 클릭하고 JSON을 선택해준다. 

그리고 내용을 입력한다. 

 

 

 

 

 

요청을 보내고 상태코드 201 Created가 나타나면 원하는 리소스가 서버에 잘 생성된 것이다. 

 

 

 

 

********************************

 

요약 & 일일회고

 

postman은 http 요청을 테스트 할 수 있는 도구이다. 

get 요청을 통해 리소스를 응답받을 수 있고 post 요청을 통해 리소스를 추가할 수 있다.

테스트할때는 반드시 상태코드를 확인해 200 OK나 201 Created 등이 잘 뜨는지 확인해야한다. 

 

**

 

REST API를 복습하고 실제로 Postman을 통해 실습했다. 복습을 하니까 그래도 조금 감이 생기는것 같다. 

어떤 상황을 가정하고 이때 REST API로 어떻게 작성해야할지 생각해보니 더 쉽게 이해할 수 있었다. 

얼른 리액트 과제랑 JS 과제 공부한것도 블로그 써야지...!! 

 

 

 

********************************

참고 링크

 

https://binit.tistory.com/17

https://chunggaeguri.tistory.com/entry/%ED%8F%AC%EC%8A%A4%ED%8A%B8%EB%A7%A8-POSTMAN-%EC%82%AC%EC%9A%A9%EB%B2%95