RESTful API란 무엇입니까?
이 섹션에서는 API가 RESTful이라는 의미와 RESTful API 호출이 구성되는 방식에 대해 설명합니다.
*API란?
API는 Application Programming Interface의 약어로, 응용 프로그램 간에 데이터를 교환하거나 서비스를 요청하고 제공하기 위한 소프트웨어 인터페이스를 의미합니다. API는 소프트웨어 개발에서 다른 애플리케이션과의 상호 작용을 위한 통로로 사용됩니다.
이 섹션에서는 RESTful API 아키텍처가 작동하는 방식에 대한 상당히 기술적인 주제를 다룹니다.
- 이러한 기본 메커니즘에 대해 자세히 알아보는 것이 유용할 수 있지만 Bubble에서 API 호출이 작동하는 방식으로 바로 건너뛰려면 아래 링크로 이동하십시오.
Bubble API 소개(중급) : 버블 Data API, 버블 Workflow API, 버블 Swagger 설정, FAQ > 바로가기
API Connector (중급) : 버블 API 커넥터 설정 및 사용, HTTP method, endpoint > 바로가기
API에 대한 글을 읽는 동안 API 용어집이 유용할 수도 있습니다.
Bubble API 용어 정리(중급) : 버블 Data API, Workflow API, 백엔드 워크플로우 종류 > 바로가기
RESTful API는 HTTP 프로토콜을 사용하여 서버와의 연결을 시작하고 응답을 받습니다.
(1) HTTP 프로토콜이란 무엇입니까?
대부분의 인터넷 사용자는 HTTP 프로토콜에 익숙합니다. 방문하는 모든 웹사이트 URL의 일부로 표시됩니다.
1. HTTP는 Hypertext Transfer Protocol로써 프로토콜입니다.
- 두 시스템 간에 데이터가 공유되는 방식을 제어하여 양 당사자가 데이터를 이해할 수 있도록 하는 일련의 규칙입니다.
- 데이터 형식을 지정하는 방법을 모른다면 두 시스템이 통신하기 어려울 것입니다.
- HTTP 프로토콜이 이를 확인합니다.
- 웹사이트를 열 때마다 브라우저는 실제로 페이지를 호스팅 하는 웹 서버에 API 호출을 하고 서버는 필요한 파일(예: HTML 및 CSS)을 다시 전송하여 응답합니다.
2. HTTP는 프로토콜이 작동하고 호출이 이루어지는 방식입니다.
- 클라이언트(예: 웹 브라우저)는 서버에 요청을 보냅니다. 요청에는 클라이언트가 어떤 종류의 작업(예: 웹 페이지 요청 또는 데이터베이스에 저장할 데이터 전송)을 원하는지에 대한 정보가 포함되며 관련 정보(예: 저장하려는 실제 데이터)도 포함될 수 있습니다.
- 서버는 요청을 받아 클라이언트가 어떤 행동을 원하는지 확인하고 처리를 진행합니다. 여기에는 html 파일을 다시 보내거나 데이터베이스에서 무언가를 찾거나 워크플로우를 실행하는 것이 포함될 수 있습니다.
- 서버는 클라이언트에게 다시 응답을 보냅니다. 응답에는 일반적으로 요청의 성공 여부를 나타내는 상태 코드가 포함되며 클라이언트가 요청한 웹 페이지와 같은 추가 데이터도 포함될 수 있습니다.
따라서 HTTP는 클라이언트와 서버가 표준화된 방식으로 서로 통신할 수 있도록 합니다. 프로토콜 자체는 매우 단순하지만 전체 웹의 기반을 구성합니다.
(2) RESTful API란 무엇입니까?
REST(Representational State Transfer)는 실제로 프로토콜이 아니라 클라이언트와 서버가 서로 상호 작용하는 방법을 정의하는 일련의 지침에 가깝습니다.
즉, 개발자는 원하는 모든 종류의 구조를 따르도록 기술적으로 API를 구축할 수 있지만 REST는 유연하고 확장 가능하며 이해하기 쉬운 API 설계에 널리 채택된 스타일입니다.
이를 통해 개발자가 동일한 통신 방법을 따르도록 준비할 때 서로 다른 시스템이 서로 쉽게 통신할 수 있습니다.
- RESTful 스타일은 몇 가지 주요 원칙을 따릅니다.
- 클라이언트-서버는 서로 완전히 독립적이며 REST API를 통해서만 통신합니다.
- 상태 비저장: 이는 서버가 요청 간에 클라이언트에 대한 정보를 저장하지 않음을 의미합니다. 따라서 각 요청은 완전히 격리되며 요청을 처리하는 데 필요한 모든 정보를 포함합니다.
- 종종 캐시저장이 가능합니다. 즉, 사용자가 동일한 데이터를 여러 번 요청하면 클라이언트가 캐시 된 응답을 사용합니다. 이렇게 하면 클라이언트 응용 프로그램의 속도가 빨라지고 서버의 부하가 줄어듭니다. Bubble은 필요한 경우가 아니면 요청을 반복하는 대신 자동으로 데이터를 캐시 합니다.
- RESTful API는 클라이언트가 서버에 직접 액세스 할 필요가 없기 때문에 종종 계층화된 것으로 설명되지만 서버의 안정성과 보안을 보장하기 위해 Proxy(프락시)와 같은 중개자에 의해 분리될 수 있습니다.
(3) RESTful API 호출의 모습
우리가 본 것처럼 REST 원칙에 기반한 API 요청을 통해 두 소프트웨어 시스템은 두 시스템이 이해하는 방식으로 서로 통신할 수 있습니다.
- 각 요청/응답은 서로 완전히 분리되어 이루어지며 서버는 해당 요청에서 요청을 처리하는 데 필요한 모든 정보를 받습니다.
- 그러나 call은 실제로 어떻게 생겼습니까? 어떤 종류의 정보가 전송되고 있습니까?
RESTful 아키텍처의 좋은 점은 양방향으로 전송되는 데이터가 컴퓨터와 사람 모두가 읽을 수 있도록 설계되었다는 것입니다.
- 각 호출은 각각 특정 목적을 수행하는 인식 가능한 부분으로 구성됩니다.
- 호출은 HTTP 프로토콜을 사용하여 이루어집니다.
1. URL ( Universal Resource Locator )
축약어 URL에 대해 들어 보셨겠지만 그 의미에 대해 많이 생각하지 않으셨을 것입니다.
- URL의 뜻은 Universal Resource Locator입니다. 이전 섹션에서 리소스의 API를 통해 액세스 할 수 있는 데이터 또는 기능의 특정 부분에 대해 설명했습니다.
URL은 해당 리소스를 찾는 방법입니다. 즉, URL은 서버의 올바른 리소스를 향한 클라이언트의 요청을 가리킵니다.
- Bubble의 데이터 API에서 엔드포인트 URL은 노출하도록 선택한 각 데이터 유형 및 API 워크플로에 대해 자동으로 생성됩니다.
- 엔드포인트의 설정은 RESTful API 접속의 첫 번째 단계로써의 의미가 있습니다. 서버가 클라이언트를 인증하고 특정 리소스에 도달하기 위한 클라이언트의 권한을 확인하려면 우리는 그들이 액세스 하려는 리소스를 알아야 합니다.
2. HTTP Method
이제 클라이언트가 접속하려는 리소스를 알았으므로 수행하려는 작업 종류를 알아야 합니다.
- 프로토콜이 되는 HTTP에 대해 논의한 것을 기억하십시오.
- 즉, HTTP 요청을 수신할 준비가 된 서버에 요청할 수 있는 가능한 작업 목록이 설정되어 있음을 의미합니다.
- 가능한 HTTP method 목록은 이보다 길지만 가장 일반적인 작업은 다음과 같습니다.
| method | 설명 |
| GET | 데이터 검색 |
| POST | 데이터 생성 |
| PUT | 데이터 업데이트 |
| PATCH | 데이터 바꾸기 |
| DELETE | 데이터 삭제 |
- 일반적으로 브라우저가 웹 페이지를 로드하기 위해 서버에 연결할 때 도메인의 루트 URL에 GET 요청을 보냅니다.
- bubble 서버는 HTML 및 CSS 파일과 같이 브라우저에서 페이지를 렌더링 하는 데 필요한 데이터로 대응하여 이러한 요청에 응답하도록 설정되었습니다.
- GET 요청에서 URL은 때때로 검색에 대한 제약 조건과 같은 매개변수(parameter)를 포함할 수 있지만 POST/PUT/PATCH/DELETE 요청에서는 일반적으로 본문 내에 매개변수가 포함됩니다.
- GET 방식 HTTP 메서드는 일부 데이터를 검색하는 데 사용됩니다. 여기에서는 HTTP 메서드가 Bubble의 API Connector에 지정되는 것으로 설명됩니다.
- 브라우저가 POST, PUT 및 DELETE 작업을 Bubble 서버에 보내 데이터베이스에서 항목을 생성, 수정 및 삭제하도록 지시합니다.
- 이제 HTTP 요청이 웹의 기초를 구성하는 이유가 이해되기 시작했습니다. 모든 웹 브라우저와 서버는 데이터를 보고, 생성하고, 편집하고, 삭제하기 위해 HTTP 동작의 언어를 사용하고 있습니다.
3. Header
모든 API 요청 및 응답에는 헤더가 포함됩니다.
- 여기에서 API와 해당 클라이언트 간에 교환되는 데이터에 대한 메타데이터 또는 정보를 찾을 수 있습니다.
- 다양한 데이터 요소가 헤더에 포함될 수 있지만 Bubble을 사용하여 작업하는 가장 일반적인 요소는 Content-type(콘텐츠 유형) 및 인증입니다.
1) Content-Type
Content-type은 적절하게 해석되고 처리될 수 있도록 전송되는 데이터의 미디어 유형(media-type)을 지정하는 데 사용됩니다.
- 예를 들어 클라이언트가 JSON 객체 형식으로 서버에 데이터를 전송하는 경우 데이터가 JSON 형식임을 나타내기 위해 값이 'application/json'인 Content-Type 헤더를 포함할 수 있습니다.
- 안약에 웹 페이지를 가져온다면 Content-type은 클라이언트가 요청에 대한 응답으로 HTML 문서를 기대하고 있음을 나타내는 'text/html' 값을 가집니다.
2) Authorization: 인증
인증에는 요청을 보내는 클라이언트를 인증하는 데 필요한 정보가 포함됩니다. Bubble의 API의 경우 Bubble은 Bearer 토큰이라는 것을 받아들입니다.
HTTP 헤더에서 해당 행은 다음과 같습니다.
Authorization: Bearer <access-token>
- Bearer는 단순히 클라이언트가 주어진 토큰의 전달자임을 의미합니다.
- 토큰은 클라이언트가 자신을 인증해야 하는 일종의 암호이며 API key라고도 합니다.
- 공개된 API call은 인증을 포함할 필요가 없습니다. API가 공개되지 않은 경우에만 필요합니다.
4.Body
body에는 POST, PATCH 또는 PUT 요청에서 전송되는 데이터와 같은 추가 데이터가 포함될 수 있습니다.(GET 요청에는 본문에 매개 변수가 포함되는 경우도 있음)
결국, 데이터베이스에서 무언가를 생성하거나 수정하려면 사용자의 이메일 및 이름과 같이 저장하려는 정보를 포함해야 보내야 합니다.
body는 URL보다 복잡하거나 더 많은 양의 데이터를 보유하는 데 더 적합합니다.
- 다음은 POST 호출 body의 예시입니다.
- 이 예시에서는 name, numbe, r isRented의 세 가지 매개변수를 사용하여 한 단위를 생성합니다.
{
"name": "Unit A",
"number": 3,
"isRented": true
}
- 이 예시에 표시되는 정보는 *JSON 형식입니다.
*JSON 형식이란 무엇입니까?
Bubble은 JSON( JavaScript Object Notation) 형식을 기반으로 합니다. 이것은 사람이 읽고 쓰기 쉽고 기계가 구문을 분석하고 생성하기 쉬운 텍스트 기반 자바스크립트 객체표현 방식입니다.
예를 들어 새 사용자를 만들고 싶다고 가정하면 본문에 다음과 같은 JSON 형식의 텍스트를 포함할 수 있습니다. { "name": "John Doe", "age": 30, "isAdmin": true } 보시다시피 JSON은 사람 눈에도 이해하기 쉽습니다. 그리고 API를 사용하여 작업하면 전송되는 내용에 대해 자세히 알아보기 위해 request 및 response의 body를 살펴보는 것이 유용할 수 있습니다.
본문에 사용할 수 있는 다른 형식은 무엇입니까?
본문의 형식이 항상 JSON인 것은 아닙니다.
- header에서 body의 형식을 지정할 수 있으므로 다른 형식도 될 수 있음을 기억하십시오.
- 서버가 기대하는 형식의 종류는 서버 설정 방법에 따라 다릅니다.
아래 목록에는 몇 가지 일반적인 형식이 있습니다.
- 가장 널리 사용되는 형식은 JSON이며 일반적으로 외부 API 문서에서 특별히 다음과 같이 지시하지 않는 한 다른 형식을 지정할 필요가 없습니다.
- Form data: HTML 양식을 제출할 때 자주 사용됩니다. 일반적으로 키-값 쌍으로 전송되며 키는 양식 필드의 이름이고 값은 필드에 입력된 데이터입니다.
- XML(Extensible Markup Language)은 구조화된 데이터를 전송하는 데 자주 사용되는 마크업 언어입니다.
- Multi part form data: 파일 업로드와 같은 대량의 이진 데이터를 보내는 데 사용되는 형식입니다.
- Plain text: HTTP 요청의 body는 간단한 데이터나 메시지를 전송하는 데 유용한 일반 텍스트일 수도 있습니다.
(4) Full Request
위의 모든 요청을 검토한 부분을 종합하면 다음과 같을 수 있습니다.
POST https://appname.bubbleapps.io/api/1.1/obj/rentalunit
Content-Type: application/json
Authorization: Bearer <access-token>
{
"unitname": "Unit A",
"unitnumber": 3,
"isRented": true
}
- 이 예시에서 URL에는 액세스 하려는 리소스(rentalunit)가 포함
- HTTP 메서드는 POST
- Header에는 Content-Type 및 Authorization이 포함
- Body에는 새로 생성하기 위해 전송되는 데이터가 포함
