RESTful API란?

🔗 [Knowledge/🌐 Web 지식] - API란 ?

 

* 위글에 이어 작성한 글입니다.

 

🙇‍♂️ 얄팍한 코딩사전 님의 유튜브를 참고하였습니다.

 

---

RESTful API를 알기 전 API에 관하여  알아보았다. 다시 간단히 정리해보자.

API란 '네가 이렇게 말하면 내가 이렇게 해 줄게' 라는 하나의 약속을 마치 메뉴판 형식처럼 정해두는 것.

API 메뉴판

 

그럼 RESTful API에 대해 본격적으로 알아보자.

 

RESTful API란? 

RESTful API는 API의 다양한 형식들 중 오늘날 가장 널리 사용되는 것이다.

API가 'A가 이렇게 요청하면 B는 이렇게 응답한다'는 약속이라면
RESTful API는 A가 어떤 방식으로 요청하고, B가 어떤 방식으로 응답할 지 지정해 놓은 다양한 형식들 중 하나이다

 

RESTful API가 다양한 형식들 중 보편적으로 쓰이는 것에는 분명한 이유가 있을 것이다.
(MBTI J들이 좋아하나ㅎ? )

 

RESTful API의 예시를 직접 살펴보면서, 이것이 왜 좋은 API의 형식인지 알아보자.

 

우리의 프로젝트 주제인 🧑‍🍳요리 레시피 사이트를 기반으로 알아보자

'현수의 레시피'라는 사이트가 있다. 이 사이트는 요리 레시피의 정보 현황을 관리한다.

이 사이트는 요리 정보가 저장된 서버와 RESTful 형식의 API 형식을 통해서 소통한다.

 

이들이 하는 일은  크게 총 4가지이다!

🚦 사실 이건 RESTful API의 공식 정의는 아니지만, 널리 알려지고 사용되는 개념이니 짚고 넘어가보자

CRUD

Create - 말 그대로 정보를 생성해서 넣는 것. 새로운 레시피의 정보를 입력하는 것.
Read - 조회, 이를테면 레시피의 목록 또는 특정 레시피의 정보를 받아와 읽는 것.
Update - 현존하는 특정 레시피의 정보를 변경하는 것.
Delete - 어느 레시피의 정보를 삭제하는 것.

💡 우리가 사용하는 대부분의 서비스들이 API를 통해 하는 일들은 이 4가지로 구성되어있다.

 

이 4가지 작업을 위한 요청들을 RESTful한 요청으로 작성해보면 다음과 같다.

Create - - POST https://api.ourhomerecipe.com/v1/recipes -새로운 레시피를 추가

Read - - - -- GET https://api.ourhomerecipe.com/v1/recipes -레시피의 목록을 받아오기
                       GET https://api.ourhomerecipe.com/v1/recipes/1 - ID가 1인 레시피의 정보를 조회

Update - -  PUT https://api.ourhomerecipe.com/v1/recipes/20 - ID가 20인 레시피의 전체 정보를 수정
                 PATCH https://api.ourhomerecipe.com/v1/recipes/13 - ID가 13인 레시피의 일부 정보를 변경

Delete- DELETE https://api.ourhomerecipe.com/v1/recipes/7 - ID가 7인 레시피를 삭제

이처럼 HTTP 프토로콜을 사용해서 이와 같읕 URI로 요청을 보내는 것을 확인.

 

HTTP는 RESTful API의 필수요소는 아니지만, RESTful API의 조건을 구현하기 용이하기 때문에
현업에서는 HTTP가 주로 사용된다.

 

💡 HTTP는 RESTful API의 핵심 원칙인 상태 없음(statelessness), 균일한 인터페이스, 리소스 기반 통신을
    자연스럽게 지원하는 프로토콜이기 때문에 RESTful API 구현에 매우 적합하다. 이따 다시 알아보자!

 

 

URL을 간단히 살펴보자!

https://api.ourhomerecipe.com/v1/recipes/1

api 를 통해 무언가의 API로 사용되고 있음을 명시.
ourhomerecipe.com 가상의 도메인 서버 주소
v1 은 API에도 변경사항이 생길 수 있으므로 버전 정보 명시.
recipes 각 요청이 어떤 데이터에 관한 것인지 명시.

 

하지만, URI만 봐서는 이 요청이 어떤 동작을 하는 것인지 모른다.

Create - - -POST https://api.ourhomerecipe.com/v1/recipes -새로운 레시피를 추가
Read - - - -- GET https://api.ourhomerecipe.com/v1/recipes -레시피의 목록을 받아오기

 

위 두 URI의 주소는 심지어 같기 때문에 구분이 되지 않는다.

자 여기서 중요한 RESTful API의 중요한 원칙이 나온다

RESTful API의 원칙

먼저, 이 URI는 이 요청이 '어떤 자원'에 관한 것인지 표현해야 하고 또 가능한  '그것만' 표현해야한다. 

 

recipes 를 통해서 이 요청들이 레시피에 관한 것임을 알 수 있다.

레시피 중 특정 레시피에 대한 요청인 경우에는 /1, /20 /13 처럼 다른 책들과 중복되지 않는 ID를 뒤에 붙혀서 명시하는 것이다.

 

'무엇을 하는가' 를 나타내는 동사는 URI에 가능한 포함되지 않는다.

어떤 종류의 작업을 할지는 이와 같은 HTTP 메소드로 표현한다.

HTTP 메소드

 ✨ 📦가 📨 보다 많은 내용을 담는다.

📦🟤 POST - 새로운 리소스 생성 (새로운 것을 등록)
📨🔵 GET - 리소스 조회 (정보를 조회)
📦🟢 PUT- 리소스 전체 수정 (전체 내용 교체)
📦🟡PATCH - 리소스 부분 수정 (일부 내용만 수정)
📨🔴DELETE - 리소스 삭제 (리소스 제거)

💡 여기서 리소스는 자원을 의미한다. 즉, 우리의 예시에서는 레시피의 정보가 리소스이다.

 

이처럼 각 요청을 어떤 색의 편지봉투, 또는 소포 상자에 담아보내는가를 통해 해당 자원에 대해 어떤 작업을 요청하는 것인지를 나타내는 것

 

이 원칙들을 알고 나면, 각 URI의 요청만 딱 봐도 이게 뭐를 어떻게 해달라는 건지 한 눈에 알 수가 있는 것이다.
즉, API가 REST 원칙을 잘 지켜서 만들어졌다면 새 API의 사용법을 큰 어려움 없이 사용법을 익힐 수 있는 것이다.

 

 

URI와 요청에 대해 살펴보자.

우선 Read 요청이다.

Read - - - -- GET https://api.ourhomerecipe.com/v1/recipes 
                       GET https://api.ourhomerecipe.com/v1/recipes/1 

이 요청들은 조회, 즉 뭔가를 보여달라는 요청이기에 많은 정보를 실어보낼 필요가 없다.

 

따라서, 📨🔵 편지 봉투로 비유한 GET 메소드로 실어보낸다.

다음과 같은 코드로 여러 레시피의 정보가 서버에서 답변으로 온다.

GET https://api.ourhomerecipe.com/v1/recipes
[
  {
    id: 1,
    title: "스파게티 볼로네제",
    ingredients: ["스파게티면", "쇠고기", "토마토 소스", "양파", "마늘"],
    description: "이탈리아 전통 파스타 요리",
    temperature: "hot"
  },
  {
    id: 2,
    title: "김치찌개",
    ingredients: ["김치", "돼지고기", "두부", "대파", "고춧가루"],
    description: "한국의 대표적인 찌개 요리",
    temperature: "hot"
  },
  {
    id: 3,
    title: "시저 샐러드",
    ingredients: ["로메인 상추", "크루통", "파마산 치즈", "시저 드레싱", "anchovies"],
    description: "신선한 채소와 풍부한 드레싱의 조화",
    temperature: "cold"
  }
]

 

 

RESTful API의 요청과 응답에는 구조화된 데이터 표현이 가능하면서도 가벼운 JSON이 많이 사용된다.

🚦JSON은 키-값 쌍으로 구성된 데이터 구조를 사용하여 정보를 저장하고 전송하는 간단하고 가벼운 형식

 

GET  https://api.ourhomerecipe.com/v1/temperature?=hot

특정 조건으로 필터링 하려면 이처럼 query parameter를 사용하면 된다.

그렇다면 temperature가 hot인 즉, 뜨거운 음식인 파스타와 찌개만 조회될 것이다.

 

GET  https://api.ourhomerecipe.com/v1/?page=1&size=10

데이터베이스의 정보를 효율적으로 가져오고 관리하기 위해 실무에서는 이와 같이 페이징 정보를 붙힌다.

 

한 페이지에 10개씩, 첫 페이지의 데이터를 보내달라는 의미이다. 

---

 

다음은 특정 레시피의 정보를 받아오는 요청이다.

GET https://api.ourhomerecipe.com/v1/recipes/1
[
  {
    id: 1,
    title: "스파게티 볼로네제",
    ingredients: ["스파게티면", "쇠고기", "토마토 소스", "양파", "마늘"],
    description: "이탈리아 전통 파스타 요리",
    temperature: "hot"
  },
  {

 

이와 같이 끝에 해당 항목의 고유 식별자를 붙여면 된다.

 

RESTful API에서 권장되는 또 다른 원칙이 있다.

Hypermedia
As
The
Engine
Of
Application State

💡각 요청의 응답에, 가용한 다른 요청들의 정보를 포함시키는 것

 

GET https://api.ourhomerecipe.com/v1/recipes/1
[
 {
  "id": 1,
  "title": "스파게티 볼로네제",
  "ingredients": ["스파게티면", "쇠고기", "토마토 소스", "양파", "마늘"],
  "description": "이탈리아 전통 파스타 요리",
  "temperature": "hot",
  "links": [
    {"rel": "self", "href": "https://api.ourhomerecipe.com/v1/recipes/1"},
    {"rel": "update", "href": "https://api.ourhomerecipe.com/v1/recipes/1"},
    {"rel": "delete", "href": "https://api.ourhomerecipe.com/v1/recipes/1"},
    {"rel": "ingredients", "href": "https://api.ourhomerecipe.com/v1/recipes/1/ingredients"},
   ]
 }
]

 

링크들을 통해 '이처럼 이 리소스에 관해 이런 기능들도 이와 같이 요청할 수 있다' 고 첨부한다.

 

이 링크 정보들을 통해, 개발자는 API 문서들을 다 뒤져보지 않아도 다음에 어떤 요청을 보낼 수 있는 지 살펴볼 수 있다.

이 부분의 API의 세부사항이 변경되더라도, 클라이언트에서 이 정보를 참조하게 만들면 클라이언트의 코드를 고칠 필요도 없어진다.

 

---

이번에는 Creat에 해당하는 POST 요청이다.

 

Create - - -POST https://api.ourhomerecipe.com/v1/recipes

 

새 항목의 정보를 입력하려면, 용량이 클 수도 있는 정보를 담아보내야한다.

따라서 📦🟤  소포상자로 비유한 POST 메소드로 실어보낸다.
POST, PUT, PATCH와 같은 소포 상자에는 body란 공간이 있어서 이곳에 용량이 큰 데이터를 실어보낼 수 있다.

POST https://api.ourhomerecipe.com/v1/recipes
{
  "title": "카프레제 샐러드",
  "ingredients": ["토마토", "모짜렐라 치즈", "바질", "올리브 오일", "발사믹 식초"],
  "description": "신선한 이탈리아 스타일의 샐러드",
  "temperature": "cold"
}

새로 등록할 레시피의 정보를 body라는 공간에 실어보낸다.

 

POST https://api.ourhomerecipe.com/v1/recipes
{
  "id" : 4,
  "title": "카프레제 샐러드",
  "ingredients": ["토마토", "모짜렐라 치즈", "바질", "올리브 오일", "발사믹 식초"],
  "description": "신선한 이탈리아 스타일의 샐러드",
  "temperature": "cold"
}

 

서버는 레시피가 성공적으로 등록되면, 이와 같이 자동으로 고유 식별번호를 부여하여 새로 추가된 정보를 응답으로 돌려준다.

 

---

다음은 UPDATE, 즉 수정하는 요청들이다.

 

Update - -  PUT https://api.ourhomerecipe.com/v1/recipes/20
                 PATCH https://api.ourhomerecipe.com/v1/recipes/20 

 

PUT과 PATCH의 차이는 전부 갈아엎느냐, 부분적으로만 수정하느냐이다.

 

수정은 특정항목에 관한 것이기 때문에 식별자를 붙여준다.

 

PUT 요청은 특정 항목의 정보를 전체적으로 대체할 때 사용된다.

때문에 그곳에 들어갈 모든 정보를 이와 같이 body에 실어보낸다.

 PUT https://api.ourhomerecipe.com/v1/recipes/20
{
  "title": "김치 볶음밥",
  "ingredients": ["밥", "김치", "돼지고기", "양파", "대파", "식용유", "참기름", "김가루", "계란"],
  "description": "한국의 대표적인 가정식 요리로, 김치의 깊은 맛과 밥의 고소함이 어우러진 든든한 한 그릇",
  "temperature": "hot",
}

{
  "message" : "recipie updated successfully."
}

이와 같이 수정된 결과를 메시지로 보내줄 수 있고, 혹은 식별자 포함 수정된 결과 전체를 보내주기도 한다.

 

---

한편, 이 값들 중 특정 값만 변경할 거라면 이렇게 전체를 수정하는 작업을 할 필요는 없을 것이다.

 

그럴 때는 이렇게 PATCH를 사용해서, 수정할 부분만 보내주면 된다.

PATCH https://api.ourhomerecipe.com/v1/recipes/20
{
  "tempearature : cold"
 }

응답으로는 역시 실행 결과를 보내주면 된다. 만약 PUT으로 보내게 된다면 나머지 값은 null값으로 갈아 치워지게 된다.

 

---

마지막으로 삭제 작업인 DELETE이다.

Delete- DELETE https://api.ourhomerecipe.com/v1/recipes/7 

이 요청은 삭제할 레시피를 지목하기만 하면 된다.

따라서📨🔴  편지 봉투면 충분하다.

{
  "message" : "recipe deleted successfully."
}

결과로는 실행 결과의 성공 여부를 보내주면 된다.

---

 

RESTful API의 특성

RESTful API의 특성은 HTTP의 특성과 같았다.

🔗  [Knowledge/🌐 Web 지식] - 세션(Session) & 토큰(JWT)

 

* 위 글의 윗 부분에  HTTP 응답상태 코드(Status Code)와 무상태성(Statelss) 이란 특성에 대해  대해 간단히 정리해놓았다.

   읽어보면 RESTful API의 특성과 직결되니 따로 정리는 하지 않겠다.

 

 

🤔HTTP 프로토콜과 REST의 특성이 겹치는 부분이 많았다. WHY?
 -🙋‍♂️ RESTful API와 HTTP의 특성이 겹치는 이유는 RESTful API가 HTTP 프로토콜을 기반으로 설계되었기 때문이다

 

    TMI : REST(Representational State Transfer)는 Roy Fielding이 2000년에 그의 박사 논문에서 제안한 아키텍처 스타일이다.
              Fielding은 HTTP의 장점을 최대한 활용할 수 있는 방식으로 원칙을 추가하여 REST를 설계했다.

---

🙇‍♂️ 결론

이처럼 RESTful API에 대해 알아보았다. 마지막으로 쉽게 정리해보자.
API가 원칙을 정해놓은 메뉴판이라면, RESTful API는 체계화된 원칙을 따르는 메뉴판이라고 볼 수 있다.

이 체계화되고 직관적인 원칙 덕분에 RESTful API는 널리 쓰이는 아키텍처가 되었다.
특히 확장성, 유연성, 독립성 등의 장점으로 인해 많은 개발자들이 선호하는 것이다.

이렇게 아키텍처부터 잘 공부하고 진행하는 것이 현명한 개발의 방법이라 생각한다.
앞으로도 RESTful API와 같은 중요한 개념들을 꾸준히 학습하며, 더욱 기본기에 충실한 개발자가 되도록 노력해야겠다. 화이팅!

 

  TMI : 생일 5일 전 ^^.. 🎂