RESTful API는 HTTP 기반의 웹 서비스 설계 패러다임으로, 자원을 중심으로 데이터를 주고받는 현대 웹 및 모바일 애플리케이션의 핵심 통신 방식입니다.
많은 개발자들이 API를 “그냥 HTTP로 만들어진 것”이라고 생각하지만, REST의 개념과 원칙을 제대로 이해하고 설계하면, 시스템의 확장성, 유지보수성, 보안성이 크게 향상됩니다.
이 글에서는 RESTful API의 기본 개념부터 설계 방법까지 자세히 다루어, 지금까지 잘못 만든 API를 개선하고자 하는 분들께 도움이 되고자 합니다.RESTful API는 현대 웹 및 모바일 애플리케이션의 핵심 통신 방식입니다. 많은 개발자들이 API를 “그냥 HTTP로 만들어진 것”이라고 생각하지만, REST의 개념과 원칙을 제대로 이해하고 설계하면, 시스템의 확장성, 유지보수성, 보안성이 크게 향상됩니다. 이 글에서는 RESTful API의 기본 개념부터 설계 방법까지 자세히 다루어, 지금까지 잘못 만든 API를 개선하고자 하는 분들께 도움이 되고자 합니다.

🔍 RESTful API란?

1. 개념 정의

• *REST(Representational State Transfer)
  *REST는 웹의 아키텍처 스타일 중 하나로, HTTP의 기본 메커니즘(메서드, 상태 코드, 헤더 등)을 활용하여 자원을 표현(Representation)하고 상태를 전이(State Transfer)하는 방법입니다.
• 자원(Resource) : API가 다루는 대상, 데이터의 단위(예: 사용자, 상품, 주문 등)는 고유한 URI를 통해 식별됩니다.
• 표현(Representation) : 자원의 상태는 JSON, XML 등으로 표현됩니다.

2. REST의 6가지 제약 조건

RESTful API를 설계할 때 지켜야 하는 핵심 제약 조건은 다음과 같습니다:

1. 클라이언트-서버 :
   클라이언트와 서버의 역할을 명확히 분리하여, 클라이언트는 UI/UX에, 서버는 데이터와 비즈니스 로직에 집중합니다.
2. 무상태(Stateless) :
   각 요청은 독립적이어야 하며, 서버는 이전 요청의 상태를 저장하지 않습니다. 필요한 모든 정보는 요청에 포함되어야 합니다.
3. 캐시 가능(Cacheable) :
   응답은 캐시 가능해야 하며, 적절한 캐시 헤더를 통해 성능을 최적화할 수 있습니다.
4. 일관된 인터페이스(Uniform Interface) :
   API의 모든 상호작용은 일관된 방식으로 진행되어야 합니다. 이를 위해 URI는 명사 형태, HTTP 메서드(GET, POST, PUT, DELETE)를 사용합니다.
5. 계층화 시스템(Layered System) :
   클라이언트는 서버의 내부 구현(프록시, 게이트웨이 등)을 알 필요 없이 API와 상호작용할 수 있어야 합니다.
6. 코드 온디맨드(Code on Demand) – 선택 사항 :
   서버가 클라이언트에 실행 가능한 코드를 전송할 수 있으나, 일반적으로는 사용하지 않습니다.

🔍 RESTful API 설계 방법 및 규칙

1. ⭐ 자원 중심 설계 (Resource-Oriented Design) ⭐

• URI 설계 : 자원을 식별하는 URI는 명사 형태로 구성합니다.
  • 예) /users (전체 사용자), /users/{userId} (특정 사용자)
• CRUD 작업: HTTP 메서드를 사용해 자원에 대한 작업을 표현합니다.
  • GET /users : 사용자 조회
  • POST /users : 사용자 생성
  • PUT /users/{userId} : 사용자 전체 업데이트
  • PATCH /users/{userId} : 사용자 일부 업데이트
  • DELETE /users/{userId} : 사용자 삭제

2. ⭐ HTTP 메소드 사용 용도 ⭐

3. ⭐ HTTP 상태 코드 활용 ⭐

• 200 OK : 요청 성공 (데이터 반환)
• 201 Created : 새로운 자원 생성 성공
• 204 No Content : 삭제나 업데이트 성공, 응답 본문 없음
• 400 Bad Request : 클라이언트 요청 오류
• 401 Unauthorized/403 Forbidden : 인증/권한 문제
• 404 Not Found : 자원 미발견
• 500 Internal Server Error : 서버 오류

4. 📌 데이터 포맷 및 버전 관리

• 데이터 포맷 : 주로 JSON을 사용합니다.
• API 버전 관리 : URI에 버전 정보를 포함하거나, 헤더를 통해 버전을 관리합니다.
  • 예: /v1/users 또는 Accept: application/vnd.example.v1+json

5. 🔒 보안 고려사항

• 인증 및 인가 : JWT, OAuth 등 보안 토큰을 사용해 접근을 제어합니다.
• HTTPS : 모든 통신은 HTTPS를 통해 암호화하여 안전하게 전송합니다.

6. 📝 문서화

• Swagger/OpenAPI : API 문서를 자동으로 생성하고, 협업 및 외부 개발자와 공유합니다.
• Postman Collection : 테스트 및 문서화 도구로 활용하여 API 사용법을 쉽게 전달할 수 있습니다.

🔍 RESTful API 설계 예시

예시 : 사용자 관리 API

GET /v1/users
  - 설명 : 모든 사용자 목록 조회
  - 응답 예시: 
    [
      { "id": 1, "name": "Alice", "email": "alice@example.com" },
      { "id": 2, "name": "Bob", "email": "bob@example.com" }
    ]

GET /v1/users/1
  - 설명: ID가 1인 사용자 조회
  - 응답 예시: 
    { "id": 1, "name": "Alice", "email": "alice@example.com" }

POST /v1/users
  - 설명: 새로운 사용자 생성
  - 요청 예시:
    {
      "name": "Charlie",
      "email": "charlie@example.com"
    }
  - 응답: 201 Created, Location 헤더에 새 리소스 URI 포함

PUT /v1/users/1
  - 설명: ID가 1인 사용자의 전체 정보 업데이트
  - 요청 예시:
    {
      "name": "Alice Smith",
      "email": "alice.smith@example.com"
    }
  - 응답: 200 OK

DELETE /v1/users/1
  - 설명: ID가 1인 사용자 삭제
  - 응답: 204 No Content

⚡ RESTful API 설계의 핵심 포인트

• 자원 중심: 모든 API는 자원(데이터) 관점에서 설계
• HTTP 메서드 활용: GET, POST, PUT/PATCH, DELETE로 CRUD 구현
• 상태 코드 및 에러 처리: 클라이언트와 서버 간의 명확한 의사소통
• 보안과 버전 관리: HTTPS, 인증, 버전 관리로 신뢰성 확보
• 문서화: Swagger 같은 도구를 활용해 명확한 API 문서 제공

⚡ RESTful API 설계 시 유의사항

• 일관성 유지 : API 전반에 걸쳐 일관된 URI 구조, 메서드 사용, 상태 코드 활용.
• 확장성 고려 : 미래에 자원이 늘어나거나, 기능이 확장될 때에도 쉽게 관리할 수 있도록 설계.
• 에러 핸들링 : 명확한 에러 메시지와 상태 코드를 제공해 클라이언트가 문제를 쉽게 파악할 수 있도록 합니다.
• 보안 강화 : 인증, 인가, HTTPS 적용 등 보안 측면을 항상 최우선으로 고려.
• 문서화 필수 : 잘 작성된 API 문서는 개발자와 사용자가 API를 쉽게 이해하고 활용할 수 있도록 돕습니다.

💡 결론

RESTful API는 자원 중심의 인터페이스로 설계함으로써, HTTP의 기본 원칙을 활용해 확장성과 유지보수성, 협업 효율성이 뛰어난 시스템을 만들 수 있습니다.
올바른 URI 설계, HTTP 메서드의 적절한 활용, 명확한 에러 처리 및 보안 강화를 통해 API의 일관성과 신뢰성을 높일 수 있으며, Swagger 같은 도구를 활용해 문서화를 철저히 하는 것이 성공적인 RESTful API 설계의 핵심입니다.

?

제목을 어떻게 지어야 할지 모르겠어서 일단 이렇게 둔다.
한번에 작성 하기도 어렵고 작업한지도 좀 오래 되서 기억을 더듬어야 하므로 계속해서 업데이트 될 예정.

사건의 발단

현재 회사에서 맡고있는 프로젝트의 WAS 중 하나가 자꾸 죽는 문제가 생겼었다.
원인은 파악 안 되고, 평일, 휴일, 밤 낮 구분없이 셧다운이 되니 미칠 노릇이였고.
원인 해결이 우선이긴 하지만 먼저 WAS가 다운되면 일단 자동으로 다시 살리도록 하기로 했다.

cron으로 서버 상태 확인 shell,

서버 재시작 shell

tomcat 7문제

JVM의 GC 설정

Linux 에서 Tomcat 재시작 하는 스크립트

테스트 서버에서 구성해 둔 Tomcat을 재기동할 때마다 일일히 shutdown 시키고, startup 하는게 귀찮아서 한방에 재시작할 수 있도록 restart.sh를 만들어 봤다.
기존의 startup.sh와 shutdown.sh가 있는 상태에서 작동한다.

#!/bin/bash
export LANG=ko_KR.UTF-8

## 이곳에 각자 경로를 넣어주면 됨
C_HOME=/usr/local/tomcat7
C_PATH=$C_HOME/bin
C_LOG=$C_HOME/logs

#echo $C_HOME
#echo $C_PATH
#echo $C_LOG

## FUNCTION WAIT FOR 5 SECS
function stanby() {
  # full bar, e.g. 20 chars
  BAR='####################'
  VAC='                    '

  for i in {1..20}; do
    # waited sec
    var=`echo "0.25*$i"|bc`
    # print $i chars of $BAR from 0 position && from $i to 20
    echo -ne "\r>> STANBY [${BAR:0:$i}${VAC:$i:20}] $var sec << "
    # wait 250ms between "frames"
    sleep .25
  done
  echo -ne "\n"
}

### CHECK IS SERVER ALIVE
function isAlive() {
  if [ -z "`ps -eaf | grep java | grep $C_PATH`" ]; then
    # END
    echo 0
  else
    # RUN
    echo 1
  fi
}


echo -e "\n\n\t\t !!>> RESTART.SH RUN `date +%Y-%m-%d' '%H:%M:%S` <<!!\n\n" >> $C_LOG/catalina.out

## RUN SHUTDOWN.SH
echo -e "\nShutdown tomcat now...\n"
bash $C_PATH/shutdown.sh

stanby

## CHECK THE PROCESS ENDED
if [ isAlive == 0 ]; then
  echo -e "\n\t>>> Tomcat was terminated successfully. <<<\n"
else
  ## IF IT HAS NOT ENDED KILL PROCESS
  ps -eaf | grep java | grep $C_PATH | awk '{print $2}' |
  while read PID
  do
    echo "Killing $PID... "
    kill -9 $PID
    echo -e "Tomcat($PID) is being killed\n"
  done

  stanby
fi

echo -e "\n\t>>> try to restart tomcat now <<<\n"

## RUN STARTUP.SH
bash $C_PATH/startup.sh

if [ isAlive == 0 ]; then
  echo -e "\n\t>>> ERROR!!! CAN NOT START TOMCAT!!  <<<"
else
  ## IF IS PROCESS RUN, CHECK USER WANNA TAIL LOG
  echo -e "\n\t>>> TOMCAT STARTUP COMMAND IS ON ACTION. <<<"
  echo -en "tail log?? (y|n) : "
  read yn

  ## TAIL LOG
  if [ $yn == "y" ] || [ $yn == "Y" ]; then
    # **CHECK DIR**
    tail -f $C_LOG/catalina.out
  fi
fi

프로세스 확인하는 함수를 따로 빼 두거나,
startup이나 shutdown의 경로를 따로 변수로 잡아주면 좋을것 같지만 일단 킵해두도록 함.

추가적으로 서버 기동 후 로그를 보는 명령어도 귀찮아서 shell 파일로 만들어 봤다.

    #!/bin/bash
    export LANG=ko_KR.UTF-8

    tail -f ../logs/catalina.out