API (Application Programming Interface) 란? / POSTMAN 기초

 

 

 

저는 초심자이므로, 직관적으로 쉽게 이해할 수 있게 API 개념을 한번 다루어 보겠습니다. 통상적으로는 API란 " 클라이언트와 서버 간의 상호작용을 정의하는 규칙과 인터페이스 "라고도 하는데요, 아무래도 문장이 잘 와닿지 않으니 보다 단순하게 설명해 보겠습니다.   

 

API란, 클라이언트와 서버 간의 소통을 위한 '통로' 역할을 하는 '추상적인' 개념입니다. 특정 기능이나 데이터를 제공하는 방법론을 정의하는 추상적인 개념이므로, 아직 구체적인 기능을 공부하지 않은 저희는 우선 API를 "클라이언트와 서버 간의 통로 역할을 해주는 것" 이라 정의해 두겠습니다.

 

 

프론트는 API라는 통로를 통해 백앤드에게 정보를 요청합니다. 백앤드는 요청에 맞는 적절한 처리를 마친 후, API를 통해 프론트에게 응답합니다. 여기서부터 알아야 할 것은,  API라는 통로를 지나려면 "해당 API에 맞는 요청과 응답 형식에 맞게" 통로 속에서의 상호작용이 이루어져야 한다는 것입니다. 서로 다른 API마다 모두 클라이언트가 어떻게 요청을 보내야 하는지, 서버가 어떻게 응답해야 하는지가 명확히 규정되어 있습니다. 

 

저희는 여러 가지 API 규칙 중, "RESTful API" 형식을 다뤄보려고 합니다.

 

RESTful API : RESTful API는 REST(Representational State Transfer) 원칙에 따라 설계된 API로, 웹 서비스에서 자원을 표현하고 조작하기 위한 표준화된 방법을 제공.

 

---

 

 

RESTful API 의 특징

 

 

• 자원 기반(Resource-Based): RESTful API는 자원을 URL로 표현합니다. 자원은 웹상의 개체(예: 사용자, 게시글 등)이며, 각 자원은 고유한 URL을 가집니다.
• HTTP 메서드 사용: RESTful API는 HTTP 메서드를 사용하여 자원에 대한 작업을 수행합니다. 주요 메서드는 다음과 같습니다:
  • GET: 자원 조회
  • POST: 자원 생성
  • PUT: 자원 업데이트
  • DELETE: 자원 삭제
• 무상태성(Stateless): 각 요청은 독립적이며, 서버는 요청 간의 상태를 저장하지 않습니다. 모든 요청은 필요한 모든 정보를 포함해야 합니다.
• 캐시 가능(Cacheable): HTTP 응답은 캐시 가능할 수 있으며, 클라이언트는 이전 응답을 재사용할 수 있습니다.

 

---

 

 

 

RESTful API를 구성하는 기본 요소

 

예시

- HTTP 메소드

 

베이스 URL: https://api.example.com

엔드포인트:

• /users - 사용자 목록을 가져오는 엔드포인트
• /users/123 - ID가 123인 사용자의 세부 정보를 가져오는 엔드포인트
• /posts - 게시글 목록을 가져오는 엔드포인트

쿼리 파라미터를 포함한 URL:

• https://api.example.com/users?page=2&limit=10
  • ?page=2 - 페이지 번호
  • &limit=10 - 한 페이지에 표시할 항목 수

 

---

 

- 그렇다면 앤드 포인트와 쿼리 파라미터의 차이는 무엇일까요?

 

 

• 앤드포인트: 자원을 식별하고 접근하기 위한 경로를 정의합니다. 주로 자원의 종류와 식별자를 포함합니다.
• 쿼리 파라미터: 요청의 세부 사항을 조정하거나 필터링하는 데 사용됩니다. 자원의 범위를 좁히거나 결과를 구체화합니다.

 

• 앤드포인트: /resource 또는 /resource/{id} 형태로 자원을 식별
• 쿼리 파라미터: ?key1=value1&key2=value2 형태로 추가적인 정보를 제공

 

 

 

---

 

 

프론트는 백에게 다양한 방식으로 정보를 요청할 수 있는데요, 바로 위 예시의 경우는 쿼리 파라미터를 통한 요청이라고 볼 수 있습니다.  POSTMAN이라는 소프트웨어를 이용하면 다음과 같은 다양한 방식의 데이터 요청이 가능합니다.

 

POSTMAN에서의 API 요청 구성

1. 쿼리 파라미터: Params 탭에서 key=value 쌍으로 입력합니다.
2. 본문 파라미터: Body 탭에서 적절한 형식을 선택하고 데이터를 입력합니다. ( ex. JSON )
3. 헤더 파라미터: Headers 탭에서 key=value 쌍으로 입력합니다. (잘 안 씀)
4. URL 파라미터: URL 경로에 직접 포함시키거나, POSTMAN의 변수 기능을 사용할 수 있습니다. (= path parameters)

 

---

 

 

 

HTTP 메소드와 API 함께 살펴보기

 

*** 이 표가 가장 중요

 

 

 

---

 

 

* POSTMAN 활용 구체적 예시

 

 

예를 들어, POSTMAN을 사용하여 다음과 같은 요청을 보냈다고 가정해봅시다:

• URL: https://api.example.com/users
• 메서드: POST
• 본문:
  json

  코드 복사

  { "name": "John Doe", "email": "john.doe@example.com" }

API 서버는 이 요청을 받아 사용자를 데이터베이스에 생성하고, 다음과 같은 응답을 보낼 수 있습니다:

• 상태 코드: 201 Created
• 응답 본문:
  json

  코드 복사

  { "id": 123, "name": "John Doe", "email": "john.doe@example.com", "createdAt": "2024-07-23T12:34:56Z" }

POSTMAN은 이 응답을 받아 화면에 표시합니다. 이 과정에서 POSTMAN은 API 서버의 요청과 응답을 중계하는 도구로 사용되는 것입니다.