API

API(Application Programming Interface)

• 프로그램(애플리케이션)끼리 서로 기능을 요청하고 결과를 전달하기 위한 인터페이스이다.

• 스마트폰 앱, 웹 브라우저, 백엔드 서버 등 다양한 소프트웨어는 API를 통해 서로 통신한다.

• API는 소프트웨어를 위한 소통 창구라고 볼 수 있다.

• 내부 구현을 알지 못해도 정해진 방법으로 기능을 사용할 수 있게 해준다.

• 단순히 동작하는 것을 넘어 사용하기 쉽고 이해하기 쉽게 설계하는 것이 중요하다.

---

REST API(Representational State Transfer)

• 서버의 자원(Resource)을 URI로 표현하고 HTTP Method를 활용하여 상태를 관리하는 설계 방식이다.

• REST는 서버가 관리하는 자원(Resource)의 상태를 표현하고 전달하는 방식이다.

  > 등록되었는가?

  > 수정되었는가?

  > 삭제되었는가?

  와 같은 자원의 상태를 클라이언트에게 전달한다.

• 클라이언트는 서버에게 자원의 상태를 요청하고, 서버는 해당 상태를 응답한다.

 

  • REST API의 주요 HTTP Method

    > GET : 조회(Read)

    > POST : 등록(Create)

    > PUT : 전체 수정(Update)

    > PATCH : 부분 수정(Update)

    > DELETE : 삭제(Delete)

---

REST의 6가지 원칙

• 균일한 인터페이스(Uniform Interface)

• 클라이언트-서버(Client-Server)

• 무상태성(Stateless)

• 캐시 가능(Cacheable)

• 계층형 시스템(Layered System)

• 주문형 코드(Code On Demand)

• REST는 좋은 API를 설계하기 위한 권장 원칙이며 반드시 모두 지켜야 하는 규칙은 아니다.

---

API 설계

• API 설계는 일관성과 예측 가능성을 위해 API를 정의하는 과정이다.

• 클라이언트와 서버가 어떤 방식으로 데이터를 주고받을지 결정한다.

• API 설계 결과를 문서로 정리한 것을 API 명세서(API Specification)라고 한다.

• API 명세서는 요청(Request), 응답(Response), URL, HTTP Method 등을 정의한 문서이다.

---

API 도출 과정

1. 누가 사용하는가? (WHO)

• API를 사용할 사용자를 정의한다.

  > 웹 브라우저

  > 모바일 앱

  > 관리자 페이지

---

2. 무엇을 다룰 것인가? (WHAT)

• 어떤 자원(Resource)을 관리할지 정의한다.

  > 회원

  > 게시글

  > 맛집

  > 댓글

---

3. 어떻게 처리할 것인가? (HOW)

• 어떤 기능을 제공할지 정의한다.

  > 등록

  > 조회

  > 수정

  > 삭제

---

4. 무엇이 필요한가? (Parameters)

• 기능 수행에 필요한 데이터를 정의한다.

  > 맛집 이름

  > 주소

  > 메뉴

  > 가격

---

5. 무엇을 반환할 것인가? (Returns)

• 작업 완료 후 클라이언트에게 전달할 데이터를 정의한다.

  > 성공 여부

  > 생성된 ID

  > 조회 결과

  > 오류 메시지

---

API 명세서 예시

맛집 등록 API

Request

Method : POST
URL : /restaurants
Content-Type : application/json
Body

{
"name": "명동교자",
"category": "한식",
"address": "서울 중구 명동10길 29"
}

Response

Status Code : 201 Created
Body

{
"id": 1,
"name": "명동교자",
"message": "맛집 등록 완료"
}

 

• 클라이언트가 맛집 정보를 서버에 전달하면 서버는 데이터를 저장한 뒤 생성된 맛집 ID와 결과 메시지를 반환한다.