3 API(Application Programming Interface)
3.1 API 비유
3.1.1 요청과 응답이 잘 이루어진 경우
상황: 고객이 식당(서버)에 들어가 메뉴판(API 문서)을 보고 정확하게 주문(요청)을 한다.
고객: “김치찌개 하나 주세요.”
점원: “네, 알겠습니다.”
(조리 후 음식 제공)
점원: “김치찌개 나왔습니다.”
→ 요청 형식도 정확했고, 식당도 해당 요청을 이해하고 정확한 응답(음식)을 제공함.
클라이언트가 올바른 형식과 내용으로 요청했고, 서버(API)가 정상적으로 처리해서 원하는 데이터를 반환한 상황이다. (200 OK)
3.1.2 요청이 잘못된 경우
상황: 고객이 메뉴판에 없는 비관련 아이템을 주문하거나, 전혀 이해할 수 없는 요청을 함.
고객: “노트북 하나 주세요.”
점원: “…저희는 식당인데요. 음식만 주문 가능합니다.”
→ 요청 대상이 잘못되어 서버(식당)가 이해할 수 없음.
클라이언트가 존재하지 않는 리소스를 요청하거나, 요청 형식이 부정확해서 서버가 요청을 처리할 수 없는 상황이다. (400 Bad Request, 404 Not Found)
3.1.3 응답이 잘못된 경우
상황: 고객은 정상적으로 주문했지만, 식당의 내부 문제로 응답이 잘못됨.
고객: “김치찌개 하나 주세요.”
점원: “네, 알겠습니다.”
(한참 후)
점원: “여기 된장찌개 나왔습니다.”
→ 요청은 맞았지만, 내부 처리 과정에서 오류가 발생해 엉뚱한 응답이 옴.
클라이언트는 올바른 요청을 했지만, 서버가 내부 오류를 일으켰거나 응답 처리 중 문제가 발생해 잘못된 데이터를 반환한 상황이다. (500 Internal Server Error 등)
3.2 API의 정의
소프트웨어/시스템이 다양한 방식(프로그래밍 가능한)으로 상호작용(데이터를 주고,받고,해석) 하기 위해서 만든 인터페이스(접점)이다. 동시에, 상호작용을 위해서 지켜야 하는 규칙을말한다.
더 정확하게, 실천적으로는 클라이언트트가 요청하고 서버가 응답하는데 필요한, 요청과 응답의 형식에 대한 약속이다.
3.2.1 API는 누가 만드나요?
API는 제공자가 규칙을 정하고, 클라이언트는 규칙을 따른다. API는 주고 받고자하는 데이터(리소스)가 있다. 어떤 데이터를 줄지는 API 제공자가 정한다. 클라이언트는 무엇을 원하는지 요청을 한다.
리소스의 제공자가 규칙을 정하기 때문에 보통 서버 개발자가 정의한다. 하지만, API를 사용하고자 하는 쪽의 편의도 중요하기 때문에 클라이언트의 사용성, 의견 등이 반영되어야 한다.
API는 기본적으로 컴퓨터 사이의 의사소통을 수월하게 하기 위해서 만들어진 것이지만 API 제공자와 사용자 사이의 의사소통이기도 하다. 만드는 쪽도, 사용하는 쪽도 모두 기술과 사람을 이해해야 좋은 API를 만들 수 있고, API를 잘 사용할 수 있다.
3.3 API의 활용
3.3.1 API 활용 사례
-
모바일 앱에서 고객이 쇼핑을 하기 위해서는 상품 리스트를 받아와야 한다.
상품리스트를 조건에 따라서 10개씩 가져오는 API가 필요하다. -
사내에서 주기적으로 협업을 하는데 매번 엑셀파일로 데이터를 주고 받으니까 일이 지연되고 파일관리의 어려움이 있다. 그때 그때 데이터를 볼 수 있으면 좋겠다. > API 로 만들어서 필요할 때마다 조회.
-
고객사가 우리 광고시스템에 등록할 광고 이미지를 매번 이미지로 전달했다. 고객사가
1000개가 넘으니까 메일함 관리도 어렵고 실수도 잦아진다.
메일이 아닌 API를 통한 광고 등록을 요청한다면 관리도 쉽고 실수를 줄일 수 있다.
3.3.2 대표적인 API 의 종류(REST, SOAP, GraphQL)
1) REST(Representational State Transfer)
자원을 이름으로 구분하고, 자원의 상태를 주고받는 방법의 API다.
HTTP프로토콜을 기반으로 웹의 자원을 다양하게 활용할 수 있다.
기본규칙
- HTTP URI(Uniform Resource Identifier)로 대상이되는 자원(Resource)을 명시한다.
- HTTP Method(POST, GET, PUT, DELETE, PATCH 등)로 동작을 명시한다.
- Header와 Body로 구성되어있다.
- Header에는 key-value로 정적인 정보를 전달한다. 주로 body를 처리하기 전에 필요한 약속, 보안과 관련 정보 등이다.
- Body에는 header에서 정의한 방식에 따라서 자유롭게 데이터를 담을 수 있다.
자유도가 높다.
- 다양한 데이터 포맷을 사용할 수 있다.
- 캐시 등 편의나 성능을 위한 기능을 사용할 수 있다.
자유도가 높다보니, RESTful 한 것이 무엇이냐? 라는 논의가 있다.
2) SOAP(Simple Object Access Protocol)
- SOAP는 그 자체로 프로토콜이다.
- 메시지 전송 포맷, 기능, 보안 등을 표준으로 정했다. 표준이 많다.
- 프로토콜상 실행 로직(성공/실패/반복)이 정의되어 있기 때문에, 처음부터 끝까지 신뢰
- 성을 제공합니다.
- 자유도가 낮다.
- 메세지가 크다.
3) GraphQL
- 비즈니스 도메인을 그래프 자료구조로 모델링하고 한 번의 요청으로 원하는 정보를 선택적으로 요청하고 전달할 수 있는 API이다.
- 한 개의 Endpoint로 모든 자료와 구조를 표현할 수 있다. 용도나 자원별로 API나 View등을 만들 필요가 없다.
- 한 번의 요청으로 원하는 모든 데이터를 서버로부터 요청하여 가져올 수 있다.
- 기존에 REST API 사용할 때 자주 발생하는 Overfetching(원하는 정보 이상을 가져온다.)이나 Underfetching(원하는 데이터를 위해 여러 요청을 보내는 것) 문제가 발생하지 않는다. - 기존 REST의 API나 리소스 단위로 캐시하던 방법의 적용이 어렵다.
- 필터링, 보안등 다양한 제약사항을 서버에서 구현하기가 어렵다.
3.3.3 OpenAPI
누구나 활용할 수 있도록 공개된 API를 말한다. 외부 소프트웨어 개발자가 빠르게 시스템을
통합할 수 있도록 하기위해서 만든다.
- API의 명세가 공개되어있다.
- 공개는 되어있지만, 일부 사용의 제약이 있을 수 있다. 요청수, 기간당 요청수 등 사용하는 사람이 많으므로, 설계와 신뢰성이 중요하다.
사례
- 공공데이터포털
- 네이버지도API
- 유튜브API
