API 기본 개념 : 패킷, 헤더, 바디, CRUD, URI, path variable, 명세서

JIYOON·2021년 7월 6일

Basic

목록 보기

1/1

📣 목표 : 패킷, 헤더, 바디, HTTP Protocol, data format, API, CRUD, URI, path variable, API 명세서를 비롯한 API의 기본 개념에 대해서 알아보자!

1️⃣ 패킷

01. 패킷 이해하기

❗️ 한 줄 정리 : 패킷이란 데이터를 전송하는 단위이다.

패킷이란, 데이터를 일정 크기로 자른 것으로 데이터 전송 단위를 의미한다.
데이터를 전송할 때 패킷이라는 기본 전송 단위로 데이터를 분해하여 전송한 후, 다시 원래의 데이터로 재조립하여 처리한다.
인터넷의 기본적인 통신 프로토콜에는 TCP/IP라는 것이 있는데, 이 프로토콜은 TCP라는 상위계층과 IP라는 하위계층으로 이루어져 있다. TCP 계층은 파일을 전송할 때 전송하기에 효율적인 크기인 패킷으로 분할하고 전송하며, IP는 각각 분할되어 번호와 인터넷 주소가 붙여진 패킷의 주소를 처리하여 패킷이 정확한 목적지에 도착할 수 있도록 한다. 이렇게 발신된 데이터는 수신한 TCP 계층의 수신부에서 원래의 파일 및 메시지로 재조립한다.

2️⃣ HTTP protocol

01. HTTP 통신 방식

TCP/IP는 클라이언트/서버 모델을 사용하는 프로토콜이며 클라이언트의 요구에 대응하여 서버가 페이지 및 데이터를 보낸다.
HTTP는 이러한 TCP/IP 프로토콜을 기반으로 한 프로토콜로, 클라이언트와 서버 간에 HTTP 요청과 HTTP 응답을 할 수 있다.
HTTP는 이전 상태를 저장하지 않는 특성을 지니는데, 각각의 요청/응답은 독립적인 요청/응답으로 전에 보낸 요청 및 응답을 알지 못한다. 따라서 이러한 진행 과정이나 데이터가 필요할 때에는 쿠키나 세션 등을 활용한다.

02. HTTP 구조

HTTP 요청(request)와 HTTP 응답(response) 모두 headers와 body라는 공통된 구조를 갖고 있는데, request에는 이에 더해 start line이, response에는 status line이라는 구조가 있다.

1) Start Line

Start Line의 구조는 다음과 같다.

HTTP Method
request가 의도한 method가 들어 있다. HTTP의 method에는 GET, POST, PUT, PATCH, DELETE 등이 있다.

❗️ 추가 : options, connect 등 다른 http method도 있으나 앞으로 작성할 API에서 주로 쓰이는 메소드는 위와 같다.

Request target
request가 전송되는 목표 URI가 담겨있다.

URI
인터넷에 있는 자원을 나타내는 주소이다. 어떤 자원을 가지고 있는 특정한 컴퓨터(서버) 상의 특정한 파일(자원)의 이름을 나타낸다.
URI이 URL과 URN의 상위 개념으로, 자원을 위치로 식별하면 URL, 고유한 이름으로 식별하면 URN이다.

uri의 구조는 위의 그림과 같다.

URL
웹 상에서 서비스를 제공하는 각 서버(컴퓨터)들에 있는 자원(파일)의 위치를 나타낸다.

URN
자원에 고유한 위치를 붙여 식별할 뿐, 자원의 위치는 포함하지 않는다.

HTTP Version
사용되는 HTTP의 버전이다.

2) Status Line

Start Line의 구조는 다음과 같다.

HTTP Version
사용되는 HTTP의 버전이다.
Status code
응답 상태를 나타내는 숫자로 되어 있는 코드이다.

❗️ 추가 공부 : HTTP status code에 대해 더 자세히 알고 싶다면 by wikipedia

Status text
응답 상태를 간단하게 설명해주는 text로 흔히 볼 수 있는 404 not found status에서 code는 404, text는 not found이다.

3) Headers

key:value 형태로 돼있으며, 추가 정보를 담고 있는 부분이다. 다음과 같은 Header 정보가 자주 사용된다.

Host : 요청이 전송되는 target의 host url
User-Agent(request) 혹은 Server(response) : 클라이언트 혹은 서버에 대한 정보
Connection : 클라이언트와 서버 사이의 커넥션을 연속적으로 유지할 것인지 응답이 도착하면 연결을 닫는 형태로 단기로만 커넥션을 유지할 것인지 지시하는 부분이다. HTTP 1.1 버전에서는 기본적으로 영속적인 커넥션을 유지하고 있다.

❗️ 추가 공부 : HTTP 커넥션에 대해서 좀 더 알고 싶다면 by MDN

Content-Type : Body의 타입을 의미한다. json 형태로 주고받는다면 application/json 값을 갖는다.
Content-Length : Body의 길이를 나타낸다.

4) Body

해당 request 혹은 response의 실제 메시지 혹은 내용이 담겨 있다.
json 형식으로 데이터를 보낸다면 다음과 같은 모양을 갖게 된다.

{
    "userId": "keepcalm",
    "message": "hello, world",
    "status": "noraml"
}

json
브라우저와 서버 간의 통신에 사용되는 표준 data format이다. 이러한 data format에는 json 뿐만 아니라 xml도 있으나, xml은 계층 구조를, json은 "userId": "keepcalm"와 같이 key:value 형태를 가진다. 간편함이나 이해도 측면에서 json이 더 높은 위치를 점하고 있어 xml은 잊혀지고 있는 추세이다.

3️⃣ RESTful API

01. API

API(Application Programming Interface, 응용 프로그램 프로그래밍 인터페이스)는 응용프로그램에서 사용할 수 있도록 기능을 제어할 수 있게 만든 인터페이스이다.

api를 버튼에 비유해 설명한 쉽게 이해할 수 있는 영상 by 노마드 코더

서버 사이드에서 API와 API 명세서를 작성함으로써 클라이언트 사이드에서 API를 활용하여 클라이언트 화면을 구성하고 개발할 수 있다.

02. REST

REST는 자원을 정의하고 이에 대한 주소를 지정하는 방법에 대한 구조적 방법론이다. 2000년에 정의된 웹 구조적 스타일을 뜻한다.

HTTP URI를 통해 접근할 자원을 명시하고, HTTP Method를 통해 해당 자원에 CRUD를 적용하여 여러 형태로 응답(json, xml, text 등)받는 것을 의미한다.

CRUD
기본적인 데이터 처리 기능인 Create(생성), Read(읽기), Update(갱신), Delete(삭제)를 묶어서 일컫는 말이다. 사용자가 기본적으로 갖추어야 할 기능을 의미한다.

03. RESTful API

RESTful API란 구조적 방법론인 REST를 기반으로 서비스 인터페이스인 API를 구현한 것을 의미한다.

HTTP URI를 통해 접근할 자원을 명시하고, HTTP Method를 통해 해당 자원에 CRUD를 적용하여 여러 형태로 응답(json, xml, text 등)받게끔 설계한 API를 뜻한다!

04. URI 설계 원칙

/(슬래시)는 계층 관계(is a)를 나타낼 때 사용한다. (animal 안에 human이 포함돼있다. human is animal.)

https://www.ojjambbong.com/animal/human

?(쿼리 스트링)은 속성(has a)를 나타낼 때 사용한다. (human은 gender라는 속성을 갖고 있다. human has a gender type.)

https://www.ojjambbong.com/animal/human?gender=female

URI의 마지막에는 /(슬래시)를 붙이지 않는다.

https://www.ojjambbong.com/animal/human/ (x)
https://www.ojjambbong.com/animal/human  (o)

URI의 가독성을 위해 _(언더바)는 사용하지 않고 -(하이픈)을 사용한다.

https://www.ojjambbong.com/animal/human?gender_type=female (x)
https://www.ojjambbong.com/animal/human?gender-type=female (o)

소문자 사용이 권장되고 파일 확장자를 포함하지 않는다.

https://www.ojjambbong.com/animal/HUMAN?gender_type=female (x)
https://www.ojjambbong.com/animal/human?image.jpeg         (x)

4️⃣ HTTP Methods

01. GET

데이터를 서버에서 받아올 때 사용되는 메소드이다.

웹서버, 데이터베이스 구축 후 백엔드 언어로 코딩하고 난 뒤 Postman 프로그램에서 위와 같이 요청을 보내면 localhost에 저장된 /app/users 위치에서 데이터(자원)를 불러온다.

pathvariable을 활용하면 인덱스를 통해 하나의 데이터만 불러오는 것도 가능하다.
데이터를 받아오는 method이기에 body를 보내지 않는 경우가 많다.
성공적으로 실행됐다면 데이터와 함께 200 status code를 받게 된다.

02. POST

데이터를 수정 및 생성할 때 사용되는 메소드이다.
주로 데이터를 수정 및 생성할 때 사용되기에 request body을 담아서 보내는 경우가 많다.

위와 같이 데이터베이스의 컬럼에 맞게 json 형식의 body를 보내서 데이터를 생성할 수 있다.

03. PUT

데이터를 수정 및 생성할 때 사용되는 메소드이다.
주로 데이터의 전체를 수정할 때 사용되며 request body에 수정 내용을 담아서 보낸다.

04. PATCH

데이터를 수정할 때 사용되는 메소드이다.
주로 데이터의 일부분을 수정할 때 사용되며 request body에 수정 내용을 담아 보낸다.
PUT과 PATCH의 차이점은 PUT은 자원의 모든 것을 업데이트하고 PATCH는 자원의 일부분을 업데이터하는 것이다.

위와 같이 path variable을 이용해 수정할 자원의 primary key(index)를 지정할 수 있다.

❗️ 주의: primary key와 index가 같은 것은 아니지만 일반적인 DBMS에서는 primary key는 자동으로 index가 적용된다.
primary key는 해당 키 값을 가지고 있는 tuple이 오직 하나라는 것을 나타내는 개념적인 값이고, index는 tuple을 보다 빨리 찾기 위해 사용되는 것이다.

❗️ DB의 구조 : 튜플이란 데이터 테이블에서 가로로 묶은 데이터셋을 의미하며, 한 객체에 대한 정보를 가지고 있는 행을 뜻한다.
(이미지 출처: 구루비스터디)

또는 위와 같이 header에 primary key를 함께 보내서 지정할 수 있다.

05. DELETE

데이터를 삭제할 때 사용되는 메소드이다.
위와 같이 uri에 path variable을 사용하여 인덱스를 지정하거나 header에 pk를 넣어서 지정할 수 있다.

최근에는 데이터가 중요해짐에 따라 DELETE 메소드를 사용하기 보다는 테이블에 status 속성을 지정하여 삭제 상태로 업데이트해주는 추세이다.

5️⃣ API 명세서

01. 목적

API의 개요와 사용법을 작성한 문서이다.
서버에서 클라이언트 개발자에게 전달해야 하므로 명확하고 직관적으로 이해할 수 있게 작성해야 한다.

❗️ 서버 개발자가 생산성 있게 개발하고 클라이언트 사이드와의 소통과 상황 공유가 원활해야 빠르게 MVP 기능까지 도달할 수 있다!

02. 예시와 들어가야 할 내용

다음은 BC카드의 API 서비스 명세서로, API의 개요와 명세가 작성돼있다.

BC카드 API 서비스 명세서

1) 인수인계 사항

1) Server : 개발 중인 server의 spec과 OS, web server, url, backend-language 등을 작성한다.
2) Account : 인스턴스, 클라우드의 계정을 작성한다.
3) Path : 웹서버와 소스파일 위치 경로를 작성한다.
4) API : 사용하는 외부 API의 id, key 등의 정보를 작성한다.