먼저, REST는 HTTP를 기반으로 클라이언트가 서버의 리소스에 접근하는 방식을 규정한 아키텍쳐이며, REST를 준수하는 API를 REST API라고 합니다.

📌 REST API의 세 가지 요소

자원(URI), 행위(HTTP요청 메서드), 표현(페이로드)

📌 REST API의 설계 원칙

1. URI는 리소스를 표현해야 한다.
2. 리소스에 대한 행위는 HTTP 요청 메서드로 표현한다.(URI에 표현하지 않는다.)

REST의 기본 원칙을 성실히 지킨 서비스 디자인을 Restful하다고 합니다.

RESTful API의 설계 원칙을 준수하여 각 리소스에 대해 일관된 메소드를 사용하면 API를 이해하기 쉽고 유지보수하기 편해집니다.

예시1) RESTful 하지 않은 예

**// 회원 관리시스템의 API 설계**

**회원 목록조회: http://test.com/member/read         --> [GET]
회원 조회:    http://test.com/member/{id}/read    --> [GET]
회원 등록:    http://test.com/member/create  --> [POST]
회원 삭제:    http://test.com/member/delete/{id}  --> [DELETE]
회원 수정:    http://test.com/member/update/{id}  --> [PUT]
회원 수정:    http://test.com/member/patch/{id}   --> [PATCH]**

API 요청에 대한 리소스 동작은 HTTP 요청 메서드를 통해 명확히 구분되며 URI는 리소스만을 나타내지만, 해당 리소스에 대한 읽기(read), 생성(create) 등의 동작을 포함하고 있습니다.

REST API의 설계 원칙을 지키지 못했으니 RESTful 하지 않습니다.

예시 2) RESTful한 API 예

**// 회원 관리시스템의 API 설계**

**회원 목록조회: http://test.com/member       --> [GET]
회원 조회:    http://test.com/member/{id}  --> [GET]
회원 등록:    http://test.com/member       --> [POST]
회원 삭제:    http://test.com/member/{id}  --> [DELETE]
회원 수정:    http://test.com/member/{id}  --> [PATCH],[PUT]**

URI는 일관되게 리소스만을 나타내며 API 요청 시 각 리소스 동작은 명확히 HTTP 요청 메서드로 구분됩니다. 이는 REST API의 설계 원칙을 따른 RESTful API입니다.

모든 상황에서 REST API의 설계원칙을 항상 지킬 수는 없습니다. 특히 HTML FORM 태그를 사용하여 API 요청을 처리할 때는 FORM이 GET 과 POST 요청만 지원하기 때문에 DELETE나 PUT과 같은 다른 HTTP 메서드를 사용하여 리소스 동작을 표현하는 것이 제한됩니다.

이런 경우에는 URI에 동사를 추가하여 URL을 형성하게 되며, FORM 태그를 사용하는 상황 이외에도 리소스 자원만을 표현한 URI와 HTTP 요청 메서드만으로 명확히 API를 이해하기 어려운 경우 URI에 동사를 포함시켜 설계합니다. 이를 컨트롤 URI라고 하며, 가독성과 명확성을 유지하기 위해 선택적으로 컨트롤 URI를 사용할 수 있습니다.

RESTful 디자인의 원칙적인 관점에서는 동사를 피하고 명사 중심의 URI를 사용하는 것이 권장되지만, 현실적인 제약 사항에 따라 동사를 사용하는 것이 더 유용할 수 있습니다. 중요한 것은 API가 일관성 있고 이해하기 쉽게 설계되어야 한다는 점입니다.

API 문서

설계된 API를 다른 사람이 잘 사용할 수 있도록 하기 위해 API 사용에 대한 설명이 필요한데, 어떻게 API를 사용해야 하는지에 대한 명확한 가이드라인을 제공하는 것이 API 문서입니다.

정확하고 이해하기 쉽게 잘 작성된 API 문서는 API를 제공하는 개발자와 API를 사용하는 개발자 간의 효율적이고 원활하게 커뮤니케이션 되도록 도와줍니다.

📌 API 문서 예시

• Kakao Developers 에서 다양한 REST API를 제공하는데, 그 API에 대한 문서를 확인해 볼 수 있습니다.

REST API 문서화 하기

API를 만들면 API를 사용할 사용자에게 API 명세서를 전달해줘야 합니다.

text파일이나 노션, 엑셀 등 작성 방법은 다양하지만, 수기로 작성해줘야합니다. 수기로 작성하면 오탈자 위험이 있습니다. api가 수정된다면 api 명세서도 수정이 되어야하지만 깜빡하고 수정해주지 않는다면 api 사용자는 이유모를 에러를 마주하게 될 수도 있습니다. 이러한 불편함을 벗어나기 위해 API를 문서화해주는 툴을 사용합니다.

Top 6 Best API Documentation Tools for Software Teams 2023

위 포스트에서 소개해주는 여러 훌륭한 api 문서화 툴 중 Swagger를 사용한 예시를 보여드리겠습니다.

기존에 만들어둔 express 프로젝트의 memberAPI에 대해 Swagger를 이용해 API 문서를 생성해보았습니다.

swagger-jsdoc과 swagger-ui-express 패키지를 설치하고 swagger 사용 환경과 생성된 API 페이지에 대한 경로를 셋팅해준 뒤, REST API 파일에 각 API에 대한 API 엔드포인트, 요청/응답 형식, 매개변수에 대한 필수 정보를 jsdoc 형식의 주석으로 넣어주면 위와 같이 API 명세서가 만들어집니다.

⬇️ (GET_ /api/member 전체 회원 목록 조회에 대한 요청과 응답 예시)

API에 대한 요청과 응답 형식에 대해 설명한대로 문서화가 잘 되었습니다.

⬇️ (GET_ /api/member 전체 회원 목록 조회에 대한 요청 TEST)

생성된 API문서를 통해 쉽게 실제 데이터가 어떤 형태로 응답되는지 테스트해 볼 수도 있습니다.

<참고한 자료>

PoiemaWeb - Rest API

API Documentation Tutorial Using Swagger JSDoc - youtube

[Swagger] Node.js Swagger API 문서화

Model: 데이터와 관련된 처리를 하는 역할

View: 사용자에게 보여지는 부분

Controller: 모델과 view를 이어주는 부분

Express 또한 MVC 패턴을 따르며 명시적으로 모델, 뷰, 컨트롤러가 분리되어 있습니다. 서버 기반에서 사용자 요청에 대한 응답 및 데이터 처리 방식이 MVC 패턴을 기반으로 설계되어있는데, 각각의 Model, View, Controller는 서로 다른 관심사를 가지고 있어 명확한 역할 분담이 이루어지고 있습니다.

1. 사용자가 google 검색창에 “후드집업” 키워드를 검색합니다.
2. 해당 요청에 대한 라우팅이 동작하며 데이터베이스로에 관련 데이터를 요청해서 가져옵니다.
3. “후드집업” 검색에 대한 결과 데이터를 템플릿엔진에 전달합니다.
4. 템플릿엔진이 해당 데이터를 반영한 UI를 처리하면 그 UI 결과를 사용자 브라우저에 응답합니다.

Model

• 입력받거나 저장되어있는 데이터에 대한 모든 처리를 담당
• DB에 저장하고 DB에서 조회하며 DB를 제어

View

• 사용자가 애플리케이션 내에서 상호 작용하는 화면
• HTML 템플릿 파일
• 템플릿 엔진(ejs, jade 등)을 사용하여 동적으로 뷰를 생성하고 렌더링
• 최종적으로 만들어진 html을 controller에 전달

Controller

• 클라이언트의 요청과 응답에 대한 처리
• Model과 상호작용하며 주소체계(URL)를 통해 요청과 응답을 제어(routes)

👩‍💻 MVC 패턴의 규칙

MVC 패턴을 제대로 사용하면 비즈니스 로직에 대한 영역과 UI 영역이 분리되므로 서로 영향을 주지 않고 독립적으로 유지될 수 있어서 유지보수가 용이해집니다. 특히 프로그램이 복잡해지고 코드가 길어질수록 이러한 원칙은 더욱 중요해집니다.

1. Model은 컨트롤러와 뷰에 의존하지 않아야 합니다.
   • Model 내부에 컨트롤러와 뷰에 관련된 코드가 있으면 안됩니다.
     • 데이터에 관련된 부분만 처리하며 언제든 깔끔하고 정제된 데이터를 꺼내 쓸 수 있도록합니다.
   • Model은 사용자가 편집하길 원하는 모든 데이터를 가지고 있어야 합니다.
   • 변경이 일어나면, 변경 통지에 대한 처리 방법을 구현해야 합니다.
2. VIew는 모델에만 의존해야 하며, Model로부터 데이터를 받을때, 반드시 Controller를 통해 받습니다.
   • Model이 가지고 있는 정보를 따로 저장해서는 안됩니다.
   • View에는 Model이나 컨트롤러에 관련된 코드는 있으면 안됩니다.
   • 모델이나 뷰는 서로의 존재를 모르고 있으며 변경 사항을 외부로 알리고 수신하는 방법만 있습니다.
   • Controller의 중재를 통해 Model롭 부터 데이터를 받습니다.
3. VIew가 Model로부터 데이터 받을 때 사용자마다 다르게 보여주어야 하는 데이터에 대해서만 받아야 합니다.
   • VIew는 사용자에게 공통적으로 보여지는 UI와 다르게 보여져야하는 UI를 합쳐져서 만들어지는 화면입니다.
   • 공통적으로 보여지는 부분에 대한 정보는 Model로부터 받는것이 아닌 VIew가 자체적으로 가지고 있어야 하는 정보여야합니다.
4. Controller에는 Model과 view의 코드가 있어도 됩니다.
   • 중재자로써 Model이나 View의 변경을 모니터링 해야 합니다.

이러한 MVC 패턴의 규칙을 잘 준수하며 개발하면 유지보수성을 높이고, 확장성을 강화할 수 있습니다.

그러나 작은 규모의 프로젝트나 간단한 API 서버를 개발할 때는 명시적인 MVC 구조 도입이 오히려 불필요할 수 있습니다. 프로젝트 규모나 복잡성이 증가하면서 코드 유지보수와 확장성이 중요해질 때, MVC 패턴을 도입 해보면 좋을 것 같습니다.

디자인 패턴에는 MVC 패턴 외에도 다양한 디자인 패턴이 있습니다. 프로젝트 특성, 팀의 개발 경험, 개발 일정 등을 고려하여 최적의 패턴을 선택하는 것이 좋겠습니다.

< 참고한 자료 출처>

MVC(Model, View, Controller) Pattern

Building and structuring a Node.js MVC application - LogRocket Blog

[10분 테코톡] 🧀 제리의 MVC 패턴

Node Express는 Node.js 환경에서 동작하는 웹 애플리케이션 프레임워크이며, Node.js 기반 웹 및 모바일 앱 개발을 지원하는 편리한 기능을 지원합니다.

편리하게 Express 프로젝트 환경 구성하기

1. npm i -g express-generator

   express-generator는 쉽게 노드 프로젝트를 생성하는데 유용한 패키지입니다. 프로젝트에 필요한 기본적인 pakage.json과 폴더 및 파일 구조 등을 잡아줍니다.

   • -g : 글로벌 위치

2. express 프로젝트명 --view=ejs

   새로운 express 프로젝트를 생성하고, 해당 프로젝트에서 템플릿 엔진으로 ejs를 사용하하여 mvc 패턴의 개발환경을 구성합니다.

3. cd 프로젝트명 , npm i , npm start

   생성된 프로젝트 폴더로 이동해서 package.json에 명시된 모듈을 설치해주고, 설치가 완료되면 현재 프로젝트를 실행해줍니다.

   • npm start명령어를 입력하면, package.json의 script 중 start 속성값으로 입력된 명령어가 실행됩니다.

       // packge.json
       "scripts": {
           "start": "node ./bin/www"
         }

   • node 명령어와 함께 bin폴더의 www파일이 실행되면서 웹서버 환경이 구성됩니다.

4. nodemon 설치 및 명령어 수정

   npm i -g nodemon 명령으로 nodemon을 설치하고, package.json의 start명령어 부분의 node 부분을 nodemon으로 수정해줍니다.

   • nodemon을 사용하면 변경사항을 저장하면 서버를 재실행시켜줘서 바로 변경사항이 반영됩니다.

Express 프로젝트 구성

noderoutingapp 이름으로 만들어진 express 프로젝트입니다.

• bin
  • www: 개발 환경에서의 백엔드 앱을 서비스하기 위한 로컬 웹서버 환경을 구성해주고 노드 백엔드 앱 서비스 서버 환경을 제공
• node_modules
  • package.json의 dependencies에 추가된 패키지와 설치된 버전이 추가됨.
• public
  • 정적인 웹 리소스 파일이 담기는 폴더(브라우저에서 호출될 소스)
• routes
  • mvc 패턴의 컨트롤러
  • 사용자 요청을 인식해서 주소체계를 통해 응답을 처리
• views
  • 템플릿 엔진을 사용하여 동적인 HTML 페이지를 생성
  • ejs 파일이 들어감

정적 페이지 렌더해보기

1. public 폴더에 sample.html 파일을 추가해서 간단히 내용을 입력한다.
2. http://localhost:3000/sample.html로 접속해본다.

라우팅 구현

기본적인 라우팅 정의입니다.

var express = require('express');
var app = express();

app.get('/', function(req, res) {
  res.send('hello world');
});

• 루트(’ / ’) 위치로 get 요청이 오는 것에 대한 라우팅 처리 입니다.
• 라우트 메소드는 get, post, delete, put 등의 HTTP 메소드 중 하나를 사용합니다.
• 첫 번째 매개변수는 라우팅할 주소를, 두 번째 매개변수에는 해당 주소체계로 라우팅 메소드와 일치하는 요청을 했을 때 어떻게 응답할지에 대한 함수를 넣어줍니다.

컨트롤러 분리해서 라우팅 구현해보기

⛳️ http://localhost:3000/sample 주소에 접속하면 views/sample/nara.ejs 파일이 렌더되도록 하기.

1. routes 폴더에 sample 라우터 파일 만들기

// routes/sample.js
var express = require('express');
var router = express.Router();

router.get('/', function (req, res, next) {
  res.render('sample/nara.ejs', { nara: '백나라' });
});

module.exports = router;

• 주소 문자열은 ‘/’ 으로 설정했지만 app.js파일에 주소체계에 대한 라우팅 설정을 따로 해줄 것 입니다.
• res.render
  • 첫 번째 매개변수: 렌더링할 ejs의 템플릿의 경로(views위치를 기준으로 작성할 것)
  • 두 번째 매개변수: 템플릿에서 사용할 변수와 값을 객체형태로 넣어줌

2. 동적으로 응답할 페이지 만들기

// views/sample/nara.ejs

<!doctype html>
<html>
  <head>
    <title><%= nara %></title>
  </head>
  <body>
    <h1><%= nara %></h1>
    <p>HI! <%= nara %></p>
  </body>
</html>

• <%= 변수명 %> 의 형태로 필요한 위치에 변수를 삽입해줍니다.
• nara라는 변수에 ‘백나라’ 라는 문자열로 html이 생성돼서 응답이 됩니다.

3. app.js에서 sample라우터를 불러와서 주소체계 정의하기

var sampleRouter = require('./routes/sample');

app.use('/sample', sampleRouter);

• 도메인주소/sample로 시작하는 모든 요청에 대해 sampleRouter가 실행됩니다.

4. http://localhost:3000/sample 접속해보기

동작 흐름

1. http://localhost:3000/sample 접속으로 GET 요청
2. /sample 로 시작하는 요청에 대해서 sampleRouter 실행
3. sampleRouter내에 주소와 get 메서드에 해당하는 라우터 실행
4. sample/nara.ejs 파일로 동적으로 html을 만들어서 응답

💡정적 페이지 위치와 라우팅 주소가 겹치면 어떻게 될까?

public 폴더의 루트 위치에 index.html 파일을 만들어보다 문득 궁금증이 생겼습니다.

브라우저에서 도메인의 루트 위치에 접속했을 때 public에 추가한 index.html이 렌더되는 것을 확인했습니다.

“ 왜 views 템플릿의 index.ejs가 렌더되지 않는걸까? “

기본적으로 index.js 파일이 routes폴더에 구성되어있고, 주소체계가 루트로 돼있어서 views의 index.ejs가 렌더되어야 할 것 같은데, 내가 추가해놓은 정적파일이 렌더되는 이유는 무엇인지 알아보았습니다.

해결 과정

우선, 정적파일이 아닌 라우터에 의한 동적파일이 렌더되도록 하려면 어떻게 해야하는지를 찾아보았습니다.

stackoverflow에 나오는 대부분의 대답은 미들웨어 위치를 옮기라는 내용이었습니다.

d아직 미들웨어에 대한 개념이 없기 때문에 미들웨어에 대해 살짝 알아보자면, 미들웨어는 서버가 요청을 받은 후 응답이 클라이언트에 전송되기 전에 작동하는 기능입니다.

express 프로젝트 환경을 구성하면 app.js에 기본적으로 정의되어있는 미들웨어들이 있는데,

app.set('views', path.join(__dirname, 'views')); // 정적 파일 설정에 대한 미들웨어
app.use('/', indexRouter); // 라우터에 대한 미들웨어

순서를 살펴보면 정적파일에 대한 설정이 먼저 정의되어 있고, 라우터에 대한 미들웨어가 나중에 정의되어있는 걸 알 수 있습니다. 미들웨어는 체인으로 배열되어 있으며 순서대로 호출됩니다.

요청이 들어오면 미들웨어가 순서대로 실행되는데, 정적 파일에 대한 미들웨어가 실행되었고 마침 적합한 index.html 정적파일이 존재했기 때문에 index.html파일을 response하면서 응답이 종료가 되어 다음 미들웨어는 실행되지 않는 것 입니다.

동일한 상황에서 정적파일이 아닌 라우팅에 의한 동적파일이 렌더되도록 하려면 정적파일에 대한 미들웨어 정의를 라우터 미들웨어 다음 순서로 옮기면 됩니다.

하지만 정적 파일 미들웨어는 정적 파일 요청에 대한 처리를 담당하므로, 정적 파일이 있는 경우 불필요한 라우팅 로직을 실행하지 않고 빠르게 응답을 생성할 수 있기 때문에 정적파일 미들웨어를 먼저 등록하는것이 권장된다고 합니다.

< 참고한 글 >

Express 앱에서 사용하기 위한 미들웨어 작성

Complete Guide to Express Middleware