📍API / RESTful API

📍 API?

📍 'Application Programming Interface'로 SW들이 서로 대화할 때 사용되는 수단. 

 

📍 ex) 시청하고 있는 youtube를 시청하기 위한 컴퓨터, 폰. 시청하는 youtube 영상들은 server라는 컴퓨터에 저장되어 있음. 각 기기들은 server로부터 영상들과 관련 데이터를 받아와 재생함. 즉 server에는 sw의 주문을 받아 서빙하는 sw가 실행되고 있다. 즉, 폰에서 youtube 앱을 켜면 youtube 앱은 server에 설치된 sw에게 '최신 컨텐츠'들의 목록을 보내달라는 요청을 함. 이에 대한 응답으로 server에서 보내줌. 그 외에도 다양한 작업들이 sw간의 대화로 이루어짐. 

 

📍 API는 server 역할을 하는 프로그램이 나눠준 메뉴판. 요청을 보내는 쪽, 즉 client 들이 보낼 수 있는 요청들이 메뉴처럼 나열되어 있다. 즉 메뉴판에 예를 들어 '다음 영상 재생하기, 댓글에 좋아요 누르기, 채널에 구독 누르기, 내 계정 정보 보기' 등등이 API에 명시. 

 

📍 SW들간에 소통하려면 서로 간의 규약 필요. 즉, '네가 이렇게 요청하면, 내가 이렇게 해 줄게,' '네가 이걸 이런 방식으로 보내주면 내가 그걸 이렇게 처리해줄게'와 같은 체계 필요. 즉, ① client에서 어떻게 요청하는 가 ② server에서 어떻게 대답하는 가 두 개 정의.

📍 example - OpenWeatherMap

📍 ① client에서 API 요청을 보내는 방법 알 수 있다. 특정 좌표의 날씨를 확인하려면 아래 주소에다가 위도/경도 적어서 보내라는 뜻.

📍 ② 사용자가 그 다음 그림과 같이 요청하면 server가 어떻게 대답을 해주는 지 나와있다.

📍 ③ 받아온 응답의 예시.

+ 받아온 데이터를 사용자가 보기 편하도록 예쁜 UI에 담아낸 것이 우리가 결과적으로 보는 앱 화면

 

📍 added

📍 API는 위 예시와 같이 특정 데이터 조회 뿐 아니라, 데이터를 새로 생성하거나 수정, 삭제 용도로도 사용된다.

ex) 포스트를 올리고, 좋아요 누르고 댓글 삭제 또한 앱에서 server로 보내는 요청으로 API에 의해 처리된다.

 

📍 API는 무엇을 보내고 무엇을 받아오는 가에 대한 것이기 때문에 언어나 프레임워크에 구애받지 않는다. API는 사양, 원칙일 뿐 뭔가를 실제로 프로그래밍한 구현체가 아니기 때문. API에 명시된 바에 따라 sw를 만들면 된다. 

ex) client가 웹 사이트라면 JavaScript로, android 폰이라면 java나 kotlin으로 요청을 보내면 된다.  / server는 다양한 언어 및 framework로 만들 수 있다. 

 

📍GUI: 일반인들이 버튼과 탭 등을 클릭하거나 눌러서 사용할 수 있도록 만들어 둔 기본적인 것들 /  API: 개발자들이 코딩해서 사용할 수 있도록 보다 고급스러운 기능들을 설명서와 함께 제시

 

📍

(1) Internal API(private API): 특정 서비스를 구성하는 sw간에 사용되는 API. 흔히 website와 mobile app과 같은 frontend가 backend server와 상호작용할 때 사용되는 API. 이 API에 따라 프론트엔드 개발자들은 요청을 보내는 코드, 백엔드 개발자들은 요청을 받아 처리하는 코드를 작성. API를 잘 만드는게 개발자들끼리도 협업에 매우 중요,

 

(2) Public API: openweathermap과 같이 모두에게 공개된 API. 자신들의 데이터와 서비스를 다른 개발자들이 가져다 쓸 수 있도록 만들어 둔 것.

📍RESTful API?

📍 API의 다양한 형식들 중 오늘날 가장 널리 사용되는 것. RESTful API는 A가 어떤 방식으로 요청하고, B가 어떤 방식으로 응답할 지 지정해 놓은 다양한 형식들 중 하나. REST(REpresentational State Transfer)에 ~ful을 붙여 'REST한 API'라는 표현으로 사용된다. 즉, REST의 기본 원칙을 성실히 지킨 서비스 디자인.

 

📍  REST는 하나의 아키텍처. Resource Oriented Architecture로 API 설계의 중심에 자원(Resource)가 있고, HTTP Method를 통해 자원을 처리하도록 설계. REST는 웹에서 데이터를 효율적으로 주고받기 위한 설계 원칙. HTTP 프로토콜을 기반으로 동작.

 

📍  RESTful API는 REST 원칙을 기반으로 Client - Server 간의 통신을 표준화하는 방식

 

📍 API를 통해 하는 일) CRUD(Create, Read, Update, Delete) 이 4가지로 구성. 

 

ex) 도서관 앱에서 위 4가지 작업을 RESTful한 요청으로 작성하면 아래와 같다.

 

: (위부터) 새 책의 정보 추가 - 책들의 목록 받아오기 - 색인정보가 1인 책의 정보 조회 - 색인정보가 20인 책의 정보 삽입 - 색인정보가 7인 책의 대여 상태 변경 - 색인번호가 123인 책 삭제

: HTTP 프로토콜 사용해서 http:// 오른쪽인 URI로 요청을 보냄. HTTP는 RESTFul API의 필수요소는 아니지만, RESTful API의 조건을 구현하기 용이하기에 현업에서 주로 HTTP 사용된다. 

: api) 무언가의 api로 사용 / yalcobooks.com은 서버의 주소 / v1으로 버전 정보(API에 변경사항 생길 수 있으므로) / 각 요청이 어떤 데이터에 관한 것인지 명시 

: RESTFul API는 위 예시와 같이 URI에 '어떤 자원'에 관한 것인지 표현해야 하고, 가능한 한 '어떤 자원'인지에 대해서만 표현해야 한다. 위 예시의 경우 책들 / + 특정 책 정보 이렇게만 명시 / 무엇을 하는 지는 URI에 가능한 한 표현 x

: 그렇다면, 어떤 종류의 작업을 할 지는 HTTP 메소드로 표현. HTTP에서는 RESTFul API로 POST, GET, PUT, PATCH, DELETE 사용. GET과 DELETE는 편지봉투에 담겨 보내지고, POST와 PUT, 그리고 PATCH는 소포 상자에 담겨 보내진다. 즉, POST, PUT, PATCH에는 GET, DELETE보다 더 많은 내용을 담을 수 있다는 뜻이다. 

 

📍 즉, 메서드 요청의 종류와 URI 자체가 목적을 명확히 나타내므로, 개발자들은 다른 팀과 협업을 하거나 어떤 public API 처음으로 사용해야 하는 상황에서도 큰 어려움 없이 새 API 사용법을 쉽게 익힐 수 있다(RESTFul API 사용법에 맞게 작성하면) 

 

* GET

📍RESTFul API의 요청과 응답에는 구조화된 데이터 표현이 가능하면서도 가벼운 JSON이 많이 사용된다. GET 결과로 특정 조건으로 필터링하려면 query parameter 사용. 예를 들어 URL 오른쪽에 ?status=available을 붙임. + 데이터베이스 구축 시 각 항목마다 고유값이 만들어지도록 설계 필수. 

 

📍HATEOS 권장(Hypermedia As The Engine Of Application State)

: 즉, 각 요청의 응답에, 가용한 다른 요청들의 정보를 포함시킨다. 이 리소스에 관해 이런 기능들도 이와 같이 요청할 수 있다고 첨부. ex) 파스타 주문 시 커피랑 디저트 메뉴판도 같이 주는 것. 즉, link:라는 정보를 통해서 개발자는 API 문서들을 다 뒤져보지 않아도 다음에 어떤 요청을 보낼 수 있는 지 살펴볼 수 있다. 

 

📍 상위/하위 리소스를 가질 수 있다. ex) 색인번호가 1인 책에 해당되는 리뷰들을 조회하려면 /reviews 붙이면 된다.

 

* POST, PUT, PATCH

: body란 공간이 있어서 용량이 큰 데이터를 실어보내고 받을 수 있다. 예를 들어 새 책을 추가하면, server에서 자동으로 부여되는 id, 색인 번호 등의 정보도 server로부터 받아진다.

 

: PUT과 PATCH의 차이는, 전부 수정인지, 일부 수정인지에 차이만 존재. PUT 요청은 특정 항목의 정보를 전체적으로 대체할 때 사용. 들어갈 모든 정보를 body에 실어보낸다. / PATCH는 특정 값의 정보만 변경한다면, 수정할 부분만 보내주면 된다. 

📍 Status Codes

📍 서버의 응답에는 요청을 처리한 결과를 알려주는 상태 코드가 담겨 온다. 모두 요청이 성공적으로 처리되면 200 OK. 성공적인 요청의 응답으로는 200번대의 상태 코드가 돌아온다 / client의 요청에 문제가 있어서 성공적으로 처리가 못되면 400번대 코드 반환 / server 측의 문제로 오류가 발생했을 때는 500번 대의 코드 반환 

📍 Stateless

📍 = '상태가 없는' 통신이다. client의 상태 정보가 server에 저장되지 말아야 한다는 것인데, server는 client에 대해 아무것도 기억하지 말아야 한다는 것이다. 따라서 client의 요청은 몇 번째 반복되든, 필요한 모든 내용을 포함하고 있어야 한다. 

📍 Cacheability

📍 client와 server 서로 간에는 계속 전혀 몰라야 하지만, 각자 자기가 어떤 응답을 보냈는 지, 자기가 어떤 응답을 받았는 지는 기억해두는 게 좋다. 한 번 얻어낸 데이터를 또 쓸 수 있도록 저장해 두는 걸 caching이라고 한다. client에서 어떤 요청에 대한 응답을 caching해두면, 같은 데이터가 필요할 때마다 요청을 보내지 않아도 되고, server도 특정 요청에 대해 응답한 바를 기억해 두면, 다른 client가 같은 요청을 보냈을 때 또 DB에서 정보를 캐낼 필요 없이, 갖고 있는 걸 바로 보내면 된다.

 

📍 RESTful API에서는 각 요청이 나타내는 바가 뚜렷하니, 캐싱 해두기가 수월. 

📍 6가지 원칙

① Uniform Interface: 일관된 인터페이스

: API 설계 시 일관된 방식으로 리소스를 처리해야 한다. 일반적으로 HTTP 메서드와 RESTful URL 구조를 준수해야 한다.

 

② Stateless(무상태)

: 서버는 클라이언트의 상태를 저장하지 않음. 각 요청(request)은 독립적이며 필요한 모든 정보를 포함해야 함. 즉, 요청마다 완전한 데이터를 제공해야 하며, 세션을 서버에서 유지하지 않음.

 

③ Caching(캐시 가능)

: 클라이언트는 서버의 응답을 caching할 수 있어야 하며, 이를 통해 성능을 향상시킬 수 있음. 응답에 Cache-Control 헤더를 설정하여 caching 기능 여부 결정.

 

④ Client-Server

: client와 server를 명확히 분리하며 각각 독립적으로 개발할 수 있도록 한다. client는 UI 및 사용자 경험을 담당하고, server는 데이터 및 비즈니스 로직 담당.

 

⑤ Hierchical System

: client는 server의 내부 구조를 알 필요 없다. API 서버는 여러 계층으로 구성될 수 있다.

 

⑥ Code on Demand:

: server가 client에 코드를 전달하여 실행할 수 있도록 지원할 수 있다. 하지만 일반적인 REST API에서는 거의 사용되지 않는다.

📍RESTful하게 API를 디자인 한다는 것은?

① 리소스와 행위를 명시적이고 직관적으로 분리

: 리소스는 URI로 표현되는 데, 리소스가 가리키는 것은 명사로 표현. 행위는 HTTP Method로 표현하고 GET / POST / PUT / PATCH / DELETE를 분명한 목적으로 사용

 

② Message는 Header와 Body를 명확하게 분리해서 사용

: entity에 대한 내용은 body에 담는다 / application server가 행동할 판단의 근거가 되는 컨트롤 정보인 API 버전 정보, 응답 받고자 하는 MIME 타입 등은 header에 담는다. header와 body는 http header와 http body로 나눌 수도 있고, http body에 들어가는 JSON 구조로 분리할 수도 있다.

 

③ API 버전 관리

: 환경은 항상 변하기에 API의 signature가 변경될 수 있다. 특정 API 변경 시 반드시 하휘호환성 보장 필수

 

④ server - client가 같은 방식을 사용해서 요청하도록 한다.

: 브라우저는 form-data 형식의 submit으로 보내고 server에서는 json 형태로 보내는 식의 분리보다는 json으로 보내든, 둘 다 form-data 형식으로 보내든 하나로 통일 / 즉, URI가 플랫폼 중립적.

📍장점 / 단점

* 장점

: OPEN API 제공 쉽다 / 멀티플랫폼 지원 및 연동 용이 / 원하는 타입으로 데이터를 주고 받을 수 있다 / 기존 웹 인프라(HTTP) 그대로 사용 가능

 

* 단점

: 사용할 수 있는 메소드 한정적 / 분산환경에는 부적합 / HTTP 통신 모델에 대해서만 지원 / 오버헤드(HTTP 요청과 응답이 많아질 경우 성능 저하 가능성) / 복잡한 관계 표현 어려움(REST는 트랜잭션이나 복잡한 관계형 데이터를 표현하는 데 적합치 않음) / 버전 관리 필요(API가 변경될 경우 client에 영향을 줄 수 있어 버전 관리 필요) 

---

 

⭐ 리소스 기반 URL 설계

 

⭐ HTTP 메서드를 활용한 CRUD

 

⭐ JSON 형식의 응답

 

⭐ client-server 구조, 무상태 원칙