📘 API에 대해

전에 간단하게 작성한 적이 있지만 최근버전으로 다시 작성해 보자한다.

API?

API는 application programming interface(응용 프로그램 프로그래밍 인터페이스)의 약자다.
말이 길어서 그렇지, 뜻은 단순하다.
서로 다른 응용 프로그램(애플리케이션)이 기능이나 데이터를 주고받기 위해 사용하는 소프트웨어 인터페이스다.

Application : 고유한 기능을 가진 모든 소프트웨어
Interface : 두 애플리케이션 간의 서비스 계약

즉 서로 다른 프로그램이 서로에게 부탁하는 방법이다.

예시

우리가 핸드폰에서 “카카오 로그인” 버튼을 누른다.

그 순간 핸드폰은 카카오 서버에게 이 아이디와 비밀번호가 맞는지 확인해줘 이렇게 말하는 셈이다.
서버는 검사 후 이에대해 로그인 성공, 로그인 실패로 대답을 한다.

이 과정이 바로 클라이언트(핸드폰) ↔ 서버(카카오톡) 구조다.

이외에도 클라이언트(핸드폰)는 메세지 전송, 친구 추가 등 수 많은 요청을 서버(카카오톡)에게 보낼 수 있다.
하지만 이러한 요청을 그때그때 알아서 처리해줘하는 식으로 서버에서 대응하는 것은 매우 비효율적이다.

그래서 미리 정해두는 것이다.

로그인 요청은 이런 형식으로 보내세요.
메시지 전송은 이런 형식으로 보내세요.
친구 목록은 이 주소로 요청하세요.

이렇게 각각의 요청을 담당하는 서버에게 요청이 잘 전달 및 처리될 수 있도록 해주는 체계가 바로 API다.

즉, 어떠한 방식으로 정보를 요청해야 하는지, 그리고 그러한 요청을 보냈을 때 어떠한 형식으로 무슨 데이터를 전달받을 수 있는지에 대해 정리한 일종의 약속이다.

이래도 이해가 안가면 더 쉽게 설명할 수 있다.

API는 식당의 메뉴판이다.
고객은 주방이 어떻게 생겼는지, 어떻게 요리를 해야하는 지 모른다.
하지만 메뉴판을 보면 불고기 버거, 콜라 등 어떤 메뉴가 있는 지 알 수 있다.
주문 시에도 “불고기 버거 하나 주세요” 이렇게 주문 하면 끝이다.
만약 메뉴판(API)가 없다? 재료가 어디있는지 부터 요리 방법까지 배워야한다.. 너무 어지운 상황이다 이건,,

API의 주요 특징

주요 특징 몇 가지만 살펴 보자

기능 제공

말 그대로 API는 특정 기능을 외부에 제공한다.
로그인 처리, 사용자 정보 조회, 게시글 작성 등 우리는 그 기능의 내부 구현을 몰라도 API를 호출하는 것만으로 해당 기능을 사용할 수 있다.

정보 은닉

내부 동작 방식을 감추고, 필요한 데이터/기능 만을 노출 시킨다.
로그인을 예시로 들면 우리는 단순히 아이디와 비밀번호를 서버에 보내지만,
서버 내부에서는 비밀번호 암호화, 데이터베이스 조회 등 여러 작업이 진행된다.
이러한 과정을 외부에 공개하지 않고 필요한 기능만 제공하는 것, 이게 바로 정보 은닉이다.
우리는 덕분에 내부 구조가 바뀌어도 외부 사용 방식은 유지될 수 있다.

표준화된 통신

API는 아무 방식으로 데이터를 주고 받지 않는다.
HTTP / HTTPS, REST, GraphQL과 같은 표준을 따른다.
즉 요청 방식과 응답 형식이 정해져 있다.

GET : 조회, POST : 생성, JSON : 데이터 형식

같이 통신 규칙이 표준화되어 있기 때문에 다른 회사, 다른 언어, 다른 시스템끼리도 문제없이 연결될 수 있다.

개발 효율 향상

API는 한 번 만들어두면 여러 서비스에서 재사용할 수 있다.
또한 팀 개발에서 동시에 작업할 수 있기에 개발 속도와 생산성이 크게 올라간다.

---

방금까지 우리는 API에 대해 알아보았다.
그렇다면 API는 아무렇게나 만들어도 될까?
기능만 잘 동작하면 끝일까?

사실 API에도 설계 방식이 존재한다. 그 중 가장 널리 사용되는 방식이 바로 REST다.

---

REST

REST(Representational State Transfer)는 자원을 중심으로 URL을 설계하고, HTTP 메서드로 행위를 구분하는 API 설계 방식이다.
벌써 말이 어렵다..쉽게 설명하면

서버 안에 있는 데이터를 주소로 구분해서, 필요할 때 가져오거나 바꾸는 방식
즉 서버를 “파일 보관함” 처럼 다룬다고 생각하면 쉽다.

• 가져오기 → GET

• 새로 넣기 → POST

• 수정하기 → PUT

• 삭제하기 → DELETE

REST API 특징

균일한 인터페이스

즉 REST는 사용 방식이 항상 비슷해야 한다는 것이다. 어떤 API는 /getUser, 어떤 API는 /userInfo.. 이런식으로 나오면 예측이 안된다.
그래서 /users, /users/1 이런식으로 형식을 자원 중심으로 통일하는 것이다.

균일한 인터페이스에는 4가지 조건이 있다.

1️⃣ 주소로 자원을 명확히 구분해라

→ /users/1 처럼 누구인지 확실히 보이게 표현

2️⃣ 클라이언트가 받은 정보만으로 이해 가능해야 한다

→ 응답 안에 필요한 데이터 다 들어있어야 한다

3️⃣ 응답에 설명이 포함되어야 한다

→ JSON 구조가 명확하고 의미가 분명해야 한다

4️⃣ 다음에 뭘 할 수 있는지도 알려줄 수 있다

→ 관련 링크나 추가 정보 제공 가능

즉 누구나 예측 가능하게 API를 만들자는 것이 균일한 인터페이스이다.

무상태 (Stateless)

제일 중요한 특징이다.

“서버는 이전 요청을 기억하지 않는다”

식당을 비유로 설명을 해보자!
우선 상태가 있는 경우에는

1. 콜라 주세요
   
2. 아까 거에 불고기 버거도 추가해주세요.
   이런식으로 주문을 할 것이다..이러면 직원은 아까의 내용을 모두 기억을 해야하는 상황이 온다.
   
   하지만 무상태 상황의 예시를 보자
   
3. 콜라 주세요
   
4. 콜라하나 불고기 버거 하나 주세요
   무상태 성이기에 두번째 주문은 첫번째 주문을 기억할 필요가 없다. 지금 들어온 주문만 처리하면 되는 것이다.
   이게 무상태성이다.
   
   API를 대입시켜 생각해보자
   상태가 있는 API인 경우에는
   1️. 로그인 요청
   2️. 서버가 이 사람 로그인했지 기억
   3️. 다음 요청에서 인증 정보 없이 처리
   즉 서버가 계속 기억해야 한다.
   
   반면 무상태성은
   
5. 로그인 → 토큰 발급
   2️. 이후 요청마다 토큰을 같이 보냄
   서버는 매 요청 시 “이 토큰이 유효한가?”, “권한이 있는가?”만 확인하고 처리한다. 이전 요청은 기억할 필요가 없다.
   
   이런식으로 무상태성은 서버가 단순해지고, 서버가 확장하기도 편리해진다.
   
   

계층화 시스템

클라이언트는 중간에 뭐가 있는지 몰라도 된다.
이건 쉽다. 클라이언트의 요청을 위해 있는 API 서버, DB등 그냥 관심 없이 오직 클라이언트는

서버랑 대화(통신)한다 라고만 생각하면 된다

캐시 가능성

다들 한번 씩은 들어봤을거다.
자주 사용하는, 자주 안 바뀌는 데이터는 저장해두고 다시 쓰자.
공통 이미지 같은 것은 매번 서버에 요청하면 귀찮지 않은가? 이걸 캐싱해서 다음번에 또 사용하면 되는 것이다.

온디맨드 코드

서버가 코드를 보내서 클라이언트 기능을 잠깐 확장할 수 있다.
예를 들면 전화번호 틀리면 바로 빨간색으로 표시되는 것이다. 서버에서 전송한 코드로 인해 이 작업을 수행할 수 있지만 자주 사용하지는 않는다.

REST API 설계

• URL에는 명사 사용 (동사 x)
  • /getAllUser ❌
  • /users, /users/{id} ✅
• URL 경로에는 소문자 사용
• 하이폰(-)은 URL 가독성 높이는데 사용
• 밑줄(_)은 URL에 사용 금지
• HTTP 메서드 활용
  • GET : 정보 요청
  • POST : 정보 생성
  • DELETE : 정보 삭제
  • PUT : 정보 전체 수정
  • PATCH : 정보 일부 수정
• HTTP 응답 상태 코드 활용
  • 200 : OK
  • 201 : Created
  • 400 : Bad Request
  • 401 : Unauthoized
  • 404 : Not Found
  • 500 : Internal Server Error
• 계층 관계는 슬래시(/)로 표현하고 URL 마지막은 슬래시 x
• 파일 확장자는 URL에 포함 x
  • http//seungje.com/api/photo.png ❌
  • http//seungje.com/api/photo ✅
• 조회시에는 쿼리 활용
  • 페이지나 필터링 정보는 쿼리 파라미터 활용
• 리소스간 관계있는 경우
  • “/리소스명/리소스ID/관계가 있는 다른 리소스명”으로 포현

REST API와 RESTful API 차이

제일 헷갈리는 부분이다.
대부분 REST API와 RESTful API는 거의 같은 말처럼 쓰인다.
하지만 약간의 차이가 있다.

REST API : REST 방식을 사용한 API

RESTful API : REST의 원칙을 잘 지킨 API

REST API 장점

마지막으로 REST를 왜 사용하는지에 대해 알아보자. 그저 설명만 나열했지 제일 중요한 그래서 왜 사용하는지에 대해서는 아직 의문이 들수도 있다.
REST 방식으로 설계된 API의 가장 큰 장점은 예측 가능성과 확장성이다. REST 방식으로 설계된 API는처음 보는 사람도 어느 정도 감으로 이해할 수 있다.

GET /users/1

이걸 보면 대부분 1번 사용자를 조회했다라는 사실을 알 수 있다. 이처럼 REST는 구조가 통일되어 있기 때문에 협업하기 좋다.
또한 REST는 무상태 구조를 따른다. 즉, 요청 하나만 봐도 서버가 처리할 수 있다.
이게 왜 중요하냐면 사용자가 많아졌을 때 서버를 여러 대로 늘리기 쉽기 때문이다. 요청이 독립적이기 때문에어느 서버가 받아도 처리 가능하다. 대형 서비스들이 REST 방식을 많이 사용하는 이유다.
마지막으로 REST는 특정 언어나 프레임워크에 묶이지 않는다.
서버는 Java로 만들고, 클라이언트는 React로 만들고, 다른 클라이언트는 Swift로 만들 수 있다. REST는 HTTP 기반이기 때문에 기술에 종속되지 않기 때문이다.

이처럼 REST는 단순히 유행해서가 아니라 위와같은 이유로 사용을 하는 것이다.