RESTful API 설명

댓글 남기기

API (Application Programming Interface)

API는 어떤 프로그램의 함수를 호출하고 결과를 받는 대화 형식을 정해놓은 것입니다. API에는 SOAP API, GraphQL API, gRPC API 등 여러 종류들이 있는데 인터넷에서 가장 많이 사용하고 있는 API 중 하나가 REST API 입니다. REST API 규약을 잘 따르면 RESTful 하다고 합니다.

Representation State Transfer (REST) API

REST API는 웹 상의 자원(Resource)을 고유한 URL을 통해 나타내고, HTTP 메소드를 사용하여 해당 자원과 관련된 작업을 수행하는 API입니다. 사용할 수 있는 메소드(행위)는 다음과 같습니다.

  • GET: 데이터를 조회하거나 검색 (Read)
  • POST: 새로운 데이터를 생성 (Create)
  • PUT: 기존 데이터를 업데이트하거나 대체 (Update)
  • PATCH: 기존 데이터의 일부를 업데이트 (Update)
    • DELETE: 데이터를 삭제 (Delete)

이러한 Create-Read-Update-Delete 작업을 CRUD 작업이라고도 합니다.

REST API는 자원 식별자, 메소드, 내용(입력값, Pay Load)으로 이루어집니다. 메소드는 위에 주어져 있고, 내용은 데이터에 관한 정보가 되겠습니다. 입출력 내용에 고정된 형식이 있는 것은 아니지만 JSON (JavaScript Object Nation)과 XML (eXtensible Markup Language) 형식을 많이 사용합니다. 자원 식별자는 뭘까요?

자원 식별자

고유한 URL을 이용해 웹 상에서 내가 원하는 자원에 접근할 수 있는데, 자원 식별을 위해 사용하는 고유한 식별자를 자원 식별자 URI (Uniform Resource Identifier)라고 합니다. URL과 URN은 모두 URI의 일종입니다.

  • URL (Uniform Resource Locator): 인터넷 상에서 자원의 위치를 나타내는 주소
  • URN (Uniform Resource Name): 자원에 대한 유일한 이름으로, 위치와 상관없이 식별 가능

상태 코드

자원 식별자, 메소드, 내용이 있으면 REST API를 호출해서 결과를 받아볼 수 있습니다. 구체적인 호출 방법은 사용하는 언어나 프로그램에 따라 달라집니다. GET 메소드의 경우 요청한 정보를 결과물로 받게 되지만, 다른 메소드(생성, 업데이트, 삭제)의 경우 서버 내에서 처리하면 되기 때문에 반환하는 데이터가 없을 수 있습니다. 그럼 요청이 정상적으로 처리되었는지 알 수가 없겠죠? 그래서 REST API에서는 항상 숫자로 된 상태 코드를 반환합니다. 숫자 범위에 따른 상태 코드입니다.

  • 2xx: 성공적인 응답 – 200은 성공적인 응답, 201은 자원이 성공적으로 생성되었음
  • 3xx: 리다이렉션 – 301은 자원 위치가 영구적으로 변경되었음, 302는 자원 위치 임시 변경
  • 4xx: 클라이언트 오류 – 400은 잘못된 요청, 404는 찾을 수 없는 자원
  • 5xx: 서버 오류 – 500은 서버 내부 오류(서버에서 요청을 처리할 수 없는 상태)

URL 주소로 웹 페이지를 열면 GET 메서드를 호출하는 셈입니다. 찾는 페이지가 없을 때 404 Error – Page not found 오류를 보신 적이 있을겁니다.

인공지능 비서와 외부 API

인공지능 비서를 만들 때 LLM은 두뇌라 할 수 있습니다. 두뇌만 있는 것보다는 손발이 있어야 더 많은 일들을 할 수 있겠죠? LLM에게 각종 함수나 API들을 손발로 쓸 수 있도록 만들어줄 수 있습니다. 파이썬에서 LLM의 API를 이용해 인공지능 비서를 만든다고 해봅시다. 다음은 LLM에게 API 사용 기술을 전수하는 과정입니다.

  • LLM에게 명령과 함께 REST API와 같은 외부 API 사용법을 알려주고 명령 수행을 위해 필요하면 API 호출을 요청하라고 알려줍니다.
  • LLM이 필요할 경우 REST API를 특정 메소드와 내용으로 호출하라고 프로그램에 요청합니다.
  • 파이썬에서는 LLM의 요청대로 REST API를 호출한 후 얻은 결과를 LLM에 알려줍니다.
  • LLM은 API 호출 결과를 가지고 계속해서 명령을 수행합니다. 필요하면 여러 개의 API를 호출할 수도 있습니다.
  • 이 과정을 주어진 명령을 완수할 때까지 반복합니다.

댓글 남기기