API

API(Application Programming Interface)는 프로그램이 다른 프로그램의 기능을 부를 수 있게 정해 둔 약속입니다. 같은 프로그램 안의 라이브러리를 부르는 API도, 네트워크 건너 다른 서버를 부르는 웹 API도 있으며, 누구나 쓰게 공개한 API를 Open API라 합니다.

서버 프로그램의 구조: MVC·DAO·DTO에서 본 층들은 한 프로그램 안에서 서로를 부릅니다. 그런데 학사 앱이 학교 서버의 학생 정보를 쓰려 할 때, 앱은 서버 안의 코드를 볼 수도 고칠 수도 없습니다. 서버가 '이 이름으로 이 값을 넘기면 이 꼴로 답한다'는 약속을 열어 두어야 앱이 부를 수 있습니다. 아래 그림은 앱이 그 약속의 창구로 요청을 넣고 답을 받는 모습과, 웹 API를 짜는 방식인 REST를 보입니다.

{  "학번": 101,  "이름": "김민수",  "학년": 3,  "학과코드": "CS"}

1부르는 약속 — 라이브러리 API와 웹 API

API의 약속에는 부르는 이름, 넘길 값, 돌려받는 꼴이 들어 있습니다. 부르는 쪽은 이 약속만 지키면 안쪽이 어떻게 짜였는지 몰라도 됩니다.

언어와 함께 오는 라이브러리의 함수도 API입니다. Java에서 Math.max(3, 7)을 부르면 둘 가운데 큰 7을 돌려받습니다. Math.max 안의 코드는 몰라도 됩니다. 웹 API는 네트워크 건너 다른 서버의 기능을 HTTP(웹에서 요청과 응답을 실어 나르는 규약) 요청으로 부르고, 답을 JSON 같은 데이터로 받습니다.

2REST — 자원 주소에 메서드를 붙인다

REST(Representational State Transfer)는 웹 API를 짜는 방식의 하나입니다. 다루는 대상을 자원(resource)이라 하고 자원마다 주소를 붙입니다. 학생 모음은 /students, 101번 학생은 /students/101입니다. 그 주소에 HTTP 메서드를 보내 할 일을 정하고, 자원의 상태는 JSON 같은 표현(representation)으로 주고받습니다.

네 일은 물리 E-R 다이어그램과 CRUD 분석의 만들기·조회·수정·삭제와 같습니다. 시험 자료는 REST를 자원·행위·표현 세 요소로 나눕니다. 자원은 주소로, 행위는 메서드로, 표현은 JSON·XML 같은 형식으로 나타납니다. JSON과 XML은 1과목 7단원 '연계 기술: XML·JSON·AJAX·REST' 레슨에서 견줍니다.

3Open API — 누구나 쓰게 연 창구

Open API는 누구나 쓸 수 있게 공개한 API입니다. 공공데이터포털의 버스 도착 정보처럼, 쓰려는 쪽이 활용을 신청해 인증키를 받고 요청마다 그 키를 붙여 부릅니다. 인증키로 누가 부르는지 가립니다.

Open API가 여는 것은 부르는 창구이고 안쪽 코드는 그대로 가려져 있습니다. 소스 코드를 공개하는 오픈 소스와 다르고, API를 적는 문서 형식인 OpenAPI 명세(OpenAPI Specification)와도 다른 말입니다.

예제

학생 자원을 REST로 열어 둔 학사 서버에 앱이 101번 학생을 청합니다.

GET /students/101

서버는 성공을 뜻하는 상태 코드 200과 함께 101번 학생의 표현을 JSON으로 돌려줍니다.

200 OK
{
  "학번": 101,
  "이름": "김민수",
  "학년": 3,
  "학과코드": "CS"
}

값은 학생 표의 101번 행과 같습니다. 같은 학생 자원에 요청 넷을 더 보냅니다. 요청마다 무슨 일인지 먼저 맞혀 보세요.

POST /students
GET /students/101
PUT /students/104
DELETE /students/107

POST와 PUT은 본문에 학생 한 명의 JSON을 실어 보냅니다.

새 학생은 아직 번호가 없어 모음 주소로 보냅니다. 나머지 셋은 번호가 붙은 한 학생의 주소로 보내고, 할 일은 메서드가 가릅니다.

시험 포인트

• 필기: API는 다른 프로그램의 기능을 부르는 약속이고, 부르는 쪽은 안쪽 코드를 몰라도 됩니다. 라이브러리 API는 같은 프로그램 안에서 함수로, 웹 API는 네트워크 건너 HTTP 요청으로 부릅니다. Open API는 누구나 쓸 수 있게 공개한 API로, 공개하는 것은 부르는 창구이지 소스 코드가 아니며 보통 인증키를 받아 씁니다. REST는 자원에 주소를 붙이고 HTTP 메서드(POST 만들기·GET 조회·PUT 수정·DELETE 삭제)로 할 일을 정하며, 자원의 상태를 JSON 같은 표현으로 주고받습니다. 오답 보기는 'Open API는 소스 코드를 공개한 것', 'GET으로 자원을 지운다'처럼 비틉니다.
• 실기: API(Application Programming Interface)·Open API(오픈 API)·REST(Representational State Transfer)로 쓰고, 메서드 이름은 GET·POST·PUT·DELETE로 씁니다.

확인 문제

1. 다음 가운데 Open API에 해당하는 것을 고르세요.

• ① 같은 회사의 두 프로그램끼리만 쓰기로 정한 주문 조회 API
• ② 인증키만 받으면 아무 회사나 주차장 빈자리 정보를 가져가게 한 시청의 API
• ③ 누구나 고쳐 쓰도록 소스 코드를 홈페이지에 올려 둔 프로그램
• ④ 계약한 협력사 한 곳에만 주소와 부르는 법을 알려 준 배송 API

2. 다음 (가)~(다)에 맞는 이름을 쓰세요. (가)·(나)는 영문 약어와 원어로, (다)는 이름만 씁니다. 답을 끝까지 쓴 뒤 정답을 펼치세요.

• (가) 결제 회사가 '카드 번호와 금액을 넘기면 승인 번호를 돌려준다'는 약속을 쇼핑몰에 알려 주었습니다. 쇼핑몰은 결제 프로그램 안을 모른 채 이 약속대로 불러 씁니다.
• (나) 도서 서버는 책마다 /books/7 같은 주소를 붙이고, 그 주소에 HTTP 메서드를 보내 할 일을 정합니다. 책의 상태는 JSON으로 주고받습니다.
• (다) 어느 기관이 미세먼지 측정값을 아무 회사나 가져다 쓰게 했습니다. 쓰려는 회사는 활용을 신청해 받은 인증키를 요청에 붙입니다.

3. 책 자원을 REST로 열어 둔 도서 서버가 있습니다. 책 모음의 주소는 /books, 한 권의 주소는 /books/번호입니다. 다음 일을 하는 요청의 첫 줄(메서드와 주소)을 쓰세요. 답을 끝까지 쓴 뒤 정답을 펼치세요.

• (1) 7번 책의 정보를 봅니다.
• (2) 새 책을 등록합니다.
• (3) 7번 책의 정보를 보낸 내용으로 바꿉니다.
• (4) 7번 책을 지웁니다.