HTTP API, 메서드와 상태코드?

API 이용 전 개념에 대해 알아보자

SwiftUI로 투두 리스트 만들기를 하며 HTTP로 서버에서 데이터를 불러오고, 저장해보기로 했다. 투두리스트를 만들어봤다고 얘기했더니 친구가 ‘야 그럼 API로도 받을 수 있냐?’ 물어봐서 일단 해 보겠다고 했다. 그런데 API가 뭔지도 모르고 하는 건 의미가 없으니 근-본 공부를 조금 해 보기로 했다.

그래서! 이에 앞서, 우선 API가 뭔지, GET과 POST가 뭔지에 대해서 공부를 해 보고 넘어가려 한다. 구현은 이 글에서!

API? GET? POST?

API(Application Programming Interface)

API는 응용 프로그램에서 사용할 수 있도록 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스를 말한다. 쉽게 말해, 프로그램들이 서로 상호작용할 수 있도록 돕는 매개체를 말하며, 특히 데이터를 주고받기 위한 방법으로 사용된다.

API는 서버와 데이터베이스에 대한 접근을 허용케 하고, 기기와 앱 사이에 데이터가 원활하게 흐를 수 있게 하며, 모든 접속을 표준화해 운영체제나 기기에 상관 없이 동일하게 사용할 수 있게 한다.

예를 들어, 내가 날씨 앱을 만들고 싶은데 이번 주 일주일 날씨에 대한 정보를 얻어야 한다면, 기상청이 제공하고 있는 일주일 날씨에 대한 정보를 받아오면 될 것이다. 이 때 기상청이 제공하는 정보를 API(공개돼있기 때문에 Open API라고 한다)라고 하고, 나는 이 API를 이용해 일주일의 날씨를 보여 주는 날씨 앱을 만들어 사용자들에게 공유할 수 있는 것이다.

즉, API는 기기에서 필요한 데이터를 운용할 수 있도록 해 주는 매개체로, 데이터를 여러 플랫폼에서 공유하기 쉽게 만들어진 것이다.

Web API

웹 API는 웹 서버 또는 웹 브라우저를 위한 API다. HTTP 표준 접근 방식을 이용하여 클라이언트, 플랫폼 환경에 구애받지 않고 사용할 수 있는 API를 말한다.

검색을 하다보니 웹 API는 RESTful API에서 어떤 요소가 빠진 것이다 이런 설명들이 있는데, 사실 잘 이해가 안 돼서 여기선 HTTP로 요청을 주고받을 수 있는 API라고 생각하고 넘어가려 한다.

RESTful

RESTful은 소프트웨어 아키텍처의 한 형식으로, HTTP 통신에서 어떤 자원에 대한 CRUD 요청을 리소스와 메서드로 표현하여 특정한 형태로 전달하는 방식을 뜻한다.

‘REST’는 Representational State Transfer의 약자로, 단어의 뜻 그대로 자원의 상태를 명시해 주고받는 것을 말한다. CRUD는 CREATE, READ, UPDATE, DELETE로, 기본적으로 컴퓨터 소프트웨어가 갖는 생성, 읽기, 갱신, 삭제의 기능을 묶어서 일컫는 단어다.

RESTful한 API는 REST인터페이스 원칙에 대한 가이드에 따라 만들어진 API로, 그 자체만으로 목적이 분명하게 보인다고 한다. 이 가이드는 다음 네 가지인데, 자세한 내용은 위키를 참고하자!

REST 인터페이스 원칙 가이드

• 자원의 식별
  • 요청 내에 기술된 개별 자원을 식별할 수 있어야 한다.
  • 웹 기반의 REST 시스템에서 URI를 사용하는 것이 그 예이다.
• 메시지를 통한 리소스의 조작
  • 클라이언트가 어떤 자원을 지칭하는 메시지와 특정 메타데이터만 가지고 서버의 자원을 변경, 삭제할 수 있어야 한다.
• 자기서술적 메시지
  • 각 메시지는 자신을 어떻게 처리해야하는지에 대한 충분한 정보를 포함해야 한다.
  • 이 메시지를 통해서 어떻게 내용을 처리하고 이용해야하는지 알 수 있어야 한다.
• 애플리케이션 상태에 대한 엔진으로서 하이퍼미디어
  • 클라이언트가 관련된 리소스에 접근하기 원한다면, 리턴되는 지시자에서 구별될 수 있어야 한다.

HTTP 메시지

MDN 문서에 따르면, HTTP 메시지는 서버와 클라이언트 간에 데이터가 교환되는 방식이며, 클라이언트가 서버로 전달하는 것을 ‘요청(request)’, 서버가 클라이언트에 요청에 대한 답변을 보내는 것을 ‘응답(response)’이라 한다.

서버와 클라이언트가 서로 소통하기 위해 공통된 기준이 있어야 할 텐데, 그 기준이 HTTP(HyperText Transfer Protocol)인 것이다.

요청과 응답의 구조는 유사하며, 다음과 같은 구조를 갖는다.

1. 시작 줄
   • 실행될 요청(HTTP 메서드), 또는 요청 수행에 대한 응답(성공/실패)
   • 항상 한 줄로 끝난다.
2. HTTP 헤더
   • 요청에 대한 설명, 메시지 본문에 대한 설명이 있다.
   • 키:값 형식으로 구성돼있다.
3. 빈 줄
   • 요청에 대한 모든 메타 정보가 전송되었음을 알리는 부분.
4. 본문(body)
   • 요청과 관련된 내용이 들어가거나, 응답과 관련된 문서가 들어간다.

시작 줄과 헤더를 묶어서 요청 헤드(head)라 하며, 반대로 HTTP 메시지의 페이로드는 본문(body)라고 한다.

HTTP 메서드

클라이언트가 서버에게 요청하고, 서버가 그에 대한 액션을 취하는 그 ‘행동’이 HTTP 메서드로 정의돼있다. 내가 할 일 정보를 받아오고 그에 대한 정보를 저장하는 과정에서 내 액션이 뭔지 지정해주는 것이 이것이다.

1. GET
   • 클라이언트가 서버에 어떠한 데이터를 받아올 때 사용
   • 오직 데이터를 받기만 한다.
2. POST
   • 클라이언트가 서버에 어떠한 데이터를 저장할 때 사용
   • 데이터 생성/수정/삭제등의 역할을 하므로 서버의 상태의 변화를 일으킨다.
3. DELETE
   • 클라이언트가 서버에 어떠한 데이터를 삭제할 때 사용
4. PUT
   • POST와 비슷한 기능으로, 클라이언트가 서버에 어떠한 데이터를 갱신할 때 사용

이 외에도, PATCH, HEAD, OPTIONS, CONNECT, TRACE 등의 메서드가 있다. 여기서 내가 사용할 메서드는 GET, POST, 그리고 DELETE다.

상태 코드

클라이언트가 요청을 보낸 내용에 대한 응답 코드를 서버가 보내는데, 컴퓨터를 모르는 사람도 아는 ‘404 에러’가 이 상태 코드에 해당한다.

상태 코드는 ‘404 에러’와 같이 3자리 숫자로 구성되어 있고, 1부터 5까지 다섯 종류로 제공된다. 4와 5는 각각 클라이언트와 서버 오류로 비정상적인 상황을, 1부터 3은 추가 요청이 필요할지라도 우선 정상적으로 작동된다는 상태를 나타낸다.

1. 100 : Continue. 지금까지의 상태가 괜찮고, 계속해서 요청을 받아들일 수 있는 상태를 말한다.
2. 200 : Ok. 요청이 성공적으로 완료되었음을 말한다.
   • 201 : Created. 요청이 성공적으로 수신됐고, 그에 대한 새로운 리소스가 생성됐다는 것을 말함. 일반적으로 POST, PUT 메서드 이후 따라옴.
   • 202 : Accepted. 요청을 수신했지만 행동할 수 없다는 것을 말함.
   • 204 : No Content. 요청에 대해 보낼 수 있는 데이터가 없음을 뜻함.
3. 300 : Multiple Choice. 요청에 대한 하나 이상의 응답이 가능함을 말하며, 이 중 하나를 반드시 선택해야 한다.
4. 400 : Bad Request. 잘못된 문법으로 인해 서버가 요청을 이해할 수 없음을 말한다.
   • 401 : Unauthorized. 클라이언트가 응답을 받기 위해선 인증을 해야 함.
   • 403 : Forbidden. 클라이언트가 접근할 권리르 갖지 않음을 뜻함. 401과 달리 클라이언트가 누군지 알고 있음.
   • 404 : Not Found. 요청받은 리소스를 찾을 수 없음을 뜻함.
5. 500 : Internal Server Error. 서버에 문제가 있음을 뜻한다.

우선 API로 데이터를 요청하고 받아오면서 처리(?)하고 봤던 상태 코드를 위주로 아주 짤막하게 정리했다. 하지만 엄청나게 많은 상태 코드가 있으니 이를 확인하려면 MDN 문서를 참고하자.