음식 주문 앱에서 메뉴 목록을 표시하고, 주문을 접수하고, 배송 상태를 업데이트하려면 백엔드의 여러 소프트웨어가 서로 데이터를 주고받아야 합니다. RESTful API는 이러한 데이터 교환 인터페이스를 설계하는 방식으로, 앱이 정해진 규칙에 따라 서버에 요청을 보내고 데이터를 받을 수 있도록 합니다.
이 글에서는 LilyTech가 RESTful API란 무엇인지 설명하고, 엔드포인트 구조를 읽는 방법과 온라인 주문 사례를 통해 자주 쓰이는 HTTP 메서드를 소개합니다. JSON 요청과 응답 예제를 살펴보면 실제 앱에서 API가 어떻게 작동하는지 이해하는 데 도움이 됩니다.
RESTful API란 무엇인가요?
API는 Application Programming Interface의 약자로, 애플리케이션 프로그래밍 인터페이스를 뜻합니다. API는 한 소프트웨어가 다른 소프트웨어에 기능이나 데이터를 요청하는 방법을 정합니다. 예를 들어 모바일 앱은 API를 호출해 서버에서 메뉴를 가져올 수 있으며, 내부적으로 데이터가 어떻게 저장되는지는 알 필요가 없습니다.

REST는 Representational State Transfer의 약자로, 웹 서비스를 설계하는 아키텍처 스타일입니다. API가 적절한 수준에서 REST 원칙에 따라 구축되면 RESTful API라고 부릅니다. 실무에서는 ‘RESTful API’라는 표현을 HTTP를 통해 리소스를 주고받는 웹 API를 가리키는 말로 흔히 사용하며, 데이터는 보통 JSON 형식으로 송수신합니다.
이 모델에서는 음식, 고객, 주문 등을 리소스로 표현합니다. 각 리소스에는 보통 엔드포인트라는 고유 주소가 있습니다. 앱은 HTTP 메서드를 사용해 엔드포인트로 요청을 보내고, 서버는 요청을 처리한 뒤 대개 상태 코드와 필요한 데이터가 포함된 응답을 반환합니다.
RESTful API는 프로그래밍 언어나 특정 제품이 아닙니다. 시스템 간 통신을 구성하는 방식입니다. 일관된 규칙을 따르면 개발팀은 웹 애플리케이션과 모바일 앱을 구축하거나 여러 소프트웨어를 보다 쉽게 연동할 수 있습니다.
엔드포인트 구조와 API 요청
음식 주문 서비스의 API 주소가 https://api.bepnhanh.vn이라고 가정해 보겠습니다. 일반적인 요청에는 HTTP 메서드, 엔드포인트, 헤더가 포함되며, 경우에 따라 본문도 함께 전송됩니다. 엔드포인트는 앱이 어떤 리소스에 접근하거나 어떤 작업을 수행하려는지 나타냅니다.
예를 들어 /api/v1/menu-items 엔드포인트는 메뉴 목록을 나타냅니다. 여기서 /api는 API 경로임을, v1은 버전을, menu-items는 리소스 그룹을 뜻합니다. 또 다른 엔드포인트인 /api/v1/orders/5821은 주문 번호 5821에 관한 작업에 사용됩니다.
메뉴 목록을 가져오는 요청은 다음과 같이 표현할 수 있습니다.
메서드 및 엔드포인트: GET https://api.bepnhanh.vn/api/v1/menu-items?category=drink
헤더: Accept: application/json
?category=drink 부분은 메뉴를 카테고리별로 필터링하는 쿼리 매개변수입니다. 헤더는 앱이 허용하는 데이터 형식이나 인증 정보 등 요청에 관한 추가 정보를 제공합니다. 주문을 생성하는 작업에는 보통 JSON 데이터가 담긴 본문도 포함됩니다.
엔드포인트를 명확하게 구성하면 API를 읽고 확장하기가 쉬워집니다. 일반적으로 /orders나 /customers처럼 리소스 이름을 명사 형태로 사용하고, HTTP 메서드로 작업을 표현합니다. 이 규칙을 따르면 작업마다 별도의 경로를 지나치게 많이 만들지 않아도 됩니다.
자주 쓰이는 HTTP 메서드 예제
HTTP 메서드는 앱이 리소스에 어떤 작업을 수행하려는지 서버에 알려줍니다. RESTful API에서 자주 쓰이는 메서드는 GET, POST, PUT, PATCH, DELETE입니다. 음식 주문 사례에서는 다음과 같이 활용할 수 있습니다.

- GET – 데이터 조회: GET /api/v1/menu-items로 메뉴 목록을 가져오거나, GET /api/v1/orders/5821로 특정 주문을 조회합니다. GET은 일반적으로 리소스를 생성하거나 수정하기 위한 데이터를 보내지 않습니다.
- POST – 리소스 생성: 메뉴와 배송 주소 정보를 포함해 POST /api/v1/orders를 보내면 새 주문을 생성합니다. 요청이 성공하면 서버는 생성된 주문 번호를 반환할 수 있습니다.
- PUT – 리소스 전체 교체: 업데이트할 전체 정보를 포함해 PUT /api/v1/orders/5821을 보냅니다. PUT은 일반적으로 리소스를 교체한다는 의미이므로, 앱은 API에서 요구하는 모든 필드를 전송해야 합니다.
- PATCH – 리소스 일부 수정: 주문 전체를 다시 보내는 대신 PATCH /api/v1/orders/5821을 사용해 상태나 배송 주소만 변경합니다.
- DELETE – 리소스 삭제: 시스템 정책에 따라 주문을 삭제하거나 취소하도록 DELETE /api/v1/orders/5821을 보냅니다.
각 작업의 구체적인 의미는 API 문서에 따라 달라집니다. 예를 들어 결제가 완료된 주문은 삭제할 수 없고 상태만 ‘취소됨’으로 변경할 수 있는 시스템도 있습니다. 따라서 앱은 서버가 안내하는 비즈니스 규칙을 따라야 합니다.
실제 JSON 요청 및 응답 예제
고객이 커피 두 잔을 주문하고 선택한 주소로 배송받는다고 가정해 보겠습니다. 앱은 주문 생성 엔드포인트로 POST 요청을 보냅니다. 본문에는 메뉴 ID, 수량, 배송 정보 등이 포함될 수 있습니다.

요청: POST /api/v1/orders
헤더: Content-Type: application/json; Authorization: Bearer <access_token>
본문: {"items": [{"menu_item_id": 42, "quantity": 2}], "delivery_address_id": 918, "note": "얼음 적게"}
Content-Type 헤더는 본문이 JSON 형식으로 전송됨을 나타냅니다. Authorization 헤더에는 서버가 주문 사용자를 확인할 수 있도록 인증 정보가 담깁니다. 실제 시스템에서는 액세스 토큰을 안전하게 보호하고 보안 연결을 통해 전송해야 하며, URL에 민감한 정보를 넣어서는 안 됩니다.
주문 생성이 성공하면 서버는 다음과 같은 응답을 반환할 수 있습니다.
응답: HTTP 201 Created
본문: {"id": 5821, "status": "pending_confirmation", "total": 98000, "currency": "VND", "created_at": "2025-03-08T10:15:00Z"}
201 Created 상태 코드는 새 리소스가 생성되었음을 의미합니다. 반환 데이터에는 주문 번호, 상태, 총액, 생성 시각이 포함됩니다. 앱은 주문 번호 5821을 사용해 주문 추적 화면으로 이동할 수 있습니다.
앱이 GET /api/v1/orders/5821을 호출하면 서버는 주문 데이터와 함께 HTTP 200 OK를 반환할 수 있습니다. 처리 과정에 따라 status 필드는 pending_confirmation에서 preparing, 다시 delivering으로 변경될 수 있습니다. 주문 번호가 없으면 서버는 404 Not Found를 반환할 수 있으며, 사용자가 로그인하지 않았거나 토큰이 유효하지 않으면 401 Unauthorized를 반환할 수 있습니다.
상태 코드를 사용하면 앱은 JSON 내용만으로 추측하지 않고 요청의 성공 여부나 오류 발생 여부를 파악할 수 있습니다. 자주 쓰이는 코드로는 정상 처리 시의 200, 전송한 데이터가 유효하지 않을 때의 400, 권한이 부족할 때의 403, 리소스를 찾을 수 없을 때의 404, 서버 오류가 발생했을 때의 500이 있습니다.
RESTful API 설계 및 연동 시 유의사항
위 예제는 이해를 돕기 위해 일부 세부 사항을 단순화했습니다. 실제 제품에 API를 적용할 때는 기업과 개발팀이 데이터 규칙, 오류 처리, 보안을 초기 단계부터 합의해야 합니다. 이러한 결정은 시스템의 연동과 유지보수에 직접적인 영향을 미칩니다.
- 일관된 엔드포인트 설계: 이해하기 쉬운 리소스 이름을 사용하고, 필요한 경우 버전을 구분하며, 데이터 필드의 명명 규칙을 통일합니다.
- 유용한 오류 응답: 적절한 상태 코드와 개발자가 처리하기에 충분히 명확한 메시지를 제공하되, 민감한 내부 정보는 노출하지 않습니다.
- 데이터 보호: HTTPS를 사용하고, 사용자를 인증하며, 역할별로 권한을 부여하고, 처리 전에 입력 데이터를 검증합니다.
- 성능 관리: 데이터가 많은 목록에는 페이지네이션, 필터링 또는 결과 수 제한을 지원하고, 과부하를 방지하기 위해 호출 빈도 제한을 고려합니다.
- 문서화 및 테스트: 개발팀이 정확하게 연동할 수 있도록 엔드포인트, 메서드, 매개변수, 응답, 발생 가능한 오류를 문서화합니다.
RESTful API는 웹사이트, 모바일 앱, 관리 시스템 또는 파트너 서비스의 연동이 필요할 때 적합한 경우가 많습니다. 다만 아키텍처 선택은 데이터, 성능, 보안, 운영 역량에 관한 요구 사항에 따라 달라집니다. 좋은 API 설계는 URL을 적절히 정하는 데 그치지 않고 기업의 업무 프로세스를 제대로 반영해야 합니다.
결론: RESTful API를 이해해 시스템을 효과적으로 연결하기
RESTful API는 리소스, 엔드포인트, HTTP 메서드를 통해 애플리케이션 간 통신을 구성하는 방식입니다. GET으로 데이터를 조회하고, POST로 주문을 생성하며, PUT이나 PATCH로 리소스를 수정하고, DELETE로 리소스를 삭제하는 방법을 이해하면 디지털 제품의 요청·응답 흐름을 쉽게 파악할 수 있습니다. JSON 구조와 상태 코드를 활용하면 정해진 규칙에 따라 데이터를 주고받을 수 있어 개발과 연동이 편리해집니다.
기업에서 웹사이트나 모바일 앱을 구축하거나 API를 ERP 및 기존 시스템과 연동하려는 경우, LilyTech가 운영 프로세스에 맞는 솔루션을 제안해 드릴 수 있습니다. 요구 사항과 효과적인 구축 방향에 대해 상담하시려면 LilyTech에 문의해 주세요.
Nguyễn Chính Ngọc Liên

