[Net] Restful API

Restful API

📌 REST(Representational State Transfer) 아키텍처 스타일을 준수하여 설계된 API입니다. 주로 HTTP 프로토콜을 기반으로 클라이언트와 서버 간에 리소스를 주고받기 위해 사용되며, 간결하고 확장 가능한 웹 서비스 설계를 제공합니다.

• REST를 잘 준수하는 API로 HTTP 프로토콜을 사용하여 클라이언트와 서버 간의 통신을 통해 자원(Resource)을 관리한다.
• 원은 고유한 URI로 식별되며, HTTP 메서드(GET, POST, PUT, DELETE 등)를 통해 다양한 작업을 수행하며 요청과 응답은 일반적으로 JSON 또는 XML 형식으로 이루어진다.

 

REST(Representational State Transfer)란?

• 자원(Resource)을 이름(Name)으로 구분하여 해당 자원의 상태(정보)를 주고받는 것을 의미한다.
• → URI를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE,PATCH 등)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 REST라 칭한다.

 

 

[1]  RESTful API의 주요 특징

1. 리소스 중심 설계
   • 모든 데이터는 **리소스(Resource)**로 표현되며, 고유한 URL을 통해 접근합니다.
   • 예: /users는 사용자 리소스를 나타냅니다.
2. 표준 HTTP 메서드 사용
   • RESTful API는 HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용해 CRUD(Create, Read, Update, Delete)를 구현합니다.
3. 상태 비저장(Stateless)
   • 서버는 클라이언트의 상태를 저장하지 않으며, 각 요청은 독립적으로 처리됩니다.
   • 클라이언트가 필요한 모든 정보를 요청에 포함해야 합니다.
4. URI를 통한 리소스 표현
   • RESTful API는 명확하고 의미 있는 URI를 사용합니다.
   • 예: /products/123는 특정 상품(ID: 123)을 나타냅니다.
5. JSON을 통한 데이터 교환
   • 요청 및 응답 데이터 형식으로 주로 JSON을 사용하지만, XML 등 다른 형식도 가능.
6. 계층화 구조
   • API 호출자는 서비스의 내부 구현이나 계층을 알 필요 없이 요청을 보낼 수 있습니다.

 

---

 

[2]  RESTful API의 구성 요소

구성 요소설명예시

리소스	API에서 관리되는 데이터.	users, products, orders
URI	리소스를 나타내는 고유한 경로.	/users/123
HTTP 메서드	리소스에 대한 동작을 정의.	GET, POST, PUT, DELETE
표현(Representation)	리소스의 데이터 표현 형식 (주로 JSON).	{ "id": 123, "name": "John" }
상태 코드	요청 처리 결과를 나타내는 HTTP 응답 코드.	200 OK, 404 Not Found

 

---

[3]  RESTful API의 HTTP 메서드와 리소스 설계

HTTP 메서드설명리소스 URI 예시배달 비유

GET	리소스 조회	/users (전체 조회)	"모든 배달 내역을 확인해 주세요."
		/users/123 (특정 조회)	"123번 주문 내역을 보여 주세요."
POST	리소스 생성	/users	"새로운 주문을 넣어 주세요."
PUT	리소스 전체 수정	/users/123	"123번 주문의 모든 항목을 수정해 주세요."
PATCH	리소스 일부 수정	/users/123	"123번 주문 중 주소만 바꿔 주세요."
DELETE	리소스 삭제	/users/123	"123번 주문을 취소해 주세요."

 

---

[4]  RESTful API의 설계 원칙

1. 자원 중심의 URI 설계
   • URI는 명확하고 직관적이어야 합니다.
     • 올바름: /users/123/orders
     • 잘못된 예: /getUserOrder?id=123
2. HTTP 상태 코드 활용
   • 상태 코드는 클라이언트가 요청 결과를 이해하는 데 도움을 줍니다.상태 코드설명

     200 OK	요청이 성공적으로 처리됨
     201 Created	새로운 리소스가 생성됨
     400 Bad Request	잘못된 요청
     404 Not Found	리소스를 찾을 수 없음
     500 Internal Server Error	서버 오류

3. 상태 비저장 설계
   • 서버는 요청 간 클라이언트의 상태를 기억하지 않아야 하며, 요청에 필요한 정보를 클라이언트가 제공해야 합니다.
4. 일관성 유지
   • 모든 API는 일관된 설계와 명명 규칙을 따릅니다.

 

---

[5]  RESTful API의 배달에 비유

• RESTful API는 배달 시스템과 비슷합니다.
  • URI: 배달 주소 (e.g., /users/123 → 특정 고객의 배달 내역).
  • HTTP 메서드: 배달 요청의 종류 (GET → 확인, POST → 새로운 주문, DELETE → 취소).
  • 상태 코드: 배달 결과 알림 (200 → 성공, 404 → 주소를 못 찾음).
  • JSON: 주문서의 상세 내용.

RESTful API는 이러한 비유처럼 직관적이고 간결한 방식으로 데이터를 주고받는 웹 서비스입니다.

 

참고자료 정리

1. 리소스는 명사를 사용해야 한다.
2. 단수가 아닌 복수 형태를 사용해야 한다.
3. 만약, REST만으로 해결하기 어려운 경우라면 동사를 허용한다.
4. 자원의 계층 관계를 슬래시(/)로 표현한다.
5. 마지막 문자에는 슬래시(/)가 있으면 안된다.
6. 언더바(_)가 아닌 하이픈(-)을 사용해야 한다.
7. 소문자를 사용해야 한다.
8. URI에 파일 확장자를 포함하면 안된다.
9. CRUD 함수명은 사용하지 않고, HTTP Method를 활용해야 한다.
10. 정렬, 필터링, 페이징은 신규 API를 만드는것이 아닌 Query Parameter를 사용해야 한다.

 

 

Maturity Model (성숙도 모델)

🐳  시스템, 프로세스, 조직, 또는 기술이 특정 목적을 얼마나 잘 달성하고 있는지를 단계별로 평가하는 구조적 접근 방식입니다. 이를 통해 조직이나 시스템이 현재 상태를 진단하고, 더 높은 수준으로 발전하기 위해 필요한 개선 사항을 명확히 할 수 있습니다.

 

[1] 성숙도 모델의 핵심 요소

1. 단계적 성장
   • 성숙도 모델은 일반적으로 5단계 또는 그 이상의 단계를 정의하며, 초기 상태부터 완성된 상태까지 점진적으로 발전하는 과정을 나타냅니다.
2. 평가 기준
   • 각 단계는 명확한 평가 기준을 가지고 있어, 현재 상태와 목표 상태를 비교하고 발전 방향을 설정할 수 있도록 돕습니다.
3. 객관적 진단
   • 조직이나 시스템의 성숙도를 객관적이고 체계적으로 진단하여 개선의 우선순위를 설정할 수 있습니다.

 

---

[2] 대표적인 성숙도 모델

1. CMMI (Capability Maturity Model Integration)

소프트웨어 개발, 서비스 관리 등의 프로세스를 개선하기 위한 대표적인 성숙도 모델.

단계설명특징

Level 1	초기화(Initiating)	비체계적, 성공은 개인 역량에 의존.
Level 2	관리(Managed)	기본 프로젝트 관리 체계가 갖춰져 있음.
Level 3	정의(Defined)	표준 프로세스 정의 및 조직 내 일관성 확보.
Level 4	정량적 관리(Quantitatively Managed)	데이터 기반 관리 및 프로세스 개선.
Level 5	최적화(Optimizing)	지속적 개선과 혁신이 이루어짐.

 

2. 데이터 성숙도 모델

데이터 관리를 중심으로 조직의 데이터 활용 능력을 평가.

단계설명특징

Level 1	초기화(Initial)	데이터 관리가 비체계적이며 중복과 오류 발생.
Level 2	관리(Managed)	데이터 품질 관리 체계 도입.
Level 3	정의(Defined)	데이터 표준화와 통합 관리 체계 확립.
Level 4	예측(Predictive)	데이터 분석을 통해 예측 가능.
Level 5	혁신(Innovative)	데이터 중심 의사결정이 가능한 혁신 조직.

 

---

[3] 성숙도 모델의 주요 활용 사례

1. 조직 관리
   • 조직의 프로세스 성숙도를 진단하고 개선 방향 설정.
2. 소프트웨어 개발
   • 개발 프로세스의 체계화와 품질 향상을 위한 CMMI 적용.
3. 데이터 관리 및 분석
   • 데이터를 전략적으로 활용하기 위한 데이터 성숙도 모델 활용.
4. 디지털 트랜스포메이션
   • 디지털화 성숙도를 평가하고 디지털 전략 수립.

 

---

[4] 성숙도 모델의 장점과 단점

구분장점단점

장점	- 현재 상태를 명확히 진단 가능.	- 모든 조직이나 시스템에 동일한 기준을 적용하기 어려움.
	- 개선 방향과 우선순위를 설정할 수 있음.	- 각 단계로 이동하는 데 시간이 오래 걸릴 수 있음.
	- 지속적 개선 문화를 정착시키는 데 도움.	- 실제 업무 상황을 반영하지 못할 경우 개선 효과가 떨어질 수 있음.
단점	- 측정 및 진단이 복잡할 수 있음.	- 초기 단계에서는 비용 대비 효과가 크지 않을 수 있음.

 

---

[5] 배달에 비유: 성숙도 모델

단계배달 예시

Level 1	"메뉴를 잘못 기록하고, 배달이 늦고, 고객 불만이 많음."
Level 2	"주문 확인 절차를 통해 기본적인 실수는 줄었으나, 고객 맞춤 서비스는 부족."
Level 3	"배달 경로와 고객 데이터를 분석하여 효율성을 높임."
Level 4	"고객의 이전 주문 기록을 바탕으로 맞춤형 추천 메뉴 제공."
Level 5	"AI를 활용한 배달 시간 예측 및 개인화된 서비스로 고객 만족도 최고조."

 

 

API Maturity Model (성숙도 모델)

• Level0
  • 웹 서비스를 제공하기 위해 URL만 매핑해 놓은 상태
  • 요청 예시(모든 요청이 단일 URI로 전송된다)

POST /operation
{
    "operation": "createUser",
    "data": {
        "name": "sparta",
        "password": "codingclub"
    }
}

 

• Level1
  • 외부로 공개하려는 리소스에 대해서 의미있는 URL로 표현하기 시작한 단계
  • 적절한 패턴을 가지고 작성 되었지만 HTTP의 메소드 별로 서비스를 구분하여 사용하고 있지는 않다.
  • 즉, 서비스 형태나 작업의 종류에 맞추어 적절한 HTTP 메소드를 지정하고 있지 않다.
  • 사용자의 요청을 GET, POST로 대부분 처리하고 에러를 반환한다.
  • 요청 예시(리소스에 대해 분리된 엔드포인트를 가진다)

POST /users
{
    "name": "sparta",
    "password": "codingclub"
}

 

• Level2
  • 우리가 제공하고자 하는 리소스를 적절하게 용도와 상태에 따라서 HTTP Methods에 맞게 설계하고 서비스하는 단계.
  • 만약 리소스의 상태가 읽기 용도로 사용되는 데이터라고 한다면 GET Method를 사용한다.
  • 새로운 리소스를 추가하는 경우는 POST Method
  • 기존 리소스의 상태를 변경하기 위해서는 PUT, PATCH Method
  • 리소스를 삭제하고자 할 때에는 Delete Method를 사용하여 서비스의 상태를 표현한다.
  • RESTful Service의 DB에 저장된 리소스를 확인하고 이러한 데이터를 조작하기 위해서 CRUD와 매칭되는 HTTP Methods를 이용하여 서비스 하는 것을 Level2 단계라고 한다.
  • HTTP의 메소드를 이용하여 리소스의 상태를 구분하여 서비스 하게 되면 비슷한 이름의 URI라 하더라도 HTTP Method에 따라서 다른 형태의 서비스를 제공할 수 있게 된다.
  • 요청 예시(HTTP Method 활용)

GET /users/123     // 특정 사용자 조회

POST /users        // 사용자 생성
{
    "name": "sparta",
    "password": "codingclub"
}

PUT /users/123     // 사용자 정보 수정
{
    "name": "java",
    "password": "spring"
}

DELETE /users/123  // 사용자 삭제

 

• Level3
  • 데이터를 가지고 그 다음 작업에서 어떠한 작업을 할 수 있는지 상태 정보를 함께 넘겨준다.
  • 클라이언트 측에서는 서버가 제공하는 서비스를 일일이 찾는 수고를 겪지 않아도 된다.
  • 엔드포인트만 가지고 있으면 서버가 제공할 수 있는 다음, 그 다음 URI값을 알 수 있다.
  • 요청 예시(응답 내에 링크를 포함한다)

💡 HATEOAS(Hypermedia As The Engine Of Application State) 회원 가입 후 회원 정보 수정은 어떻게 해야 하는지, 조회는 어떻게 해야 하는지 회원 조회를 하면서 그다음 단계로 진행할 수 있는 또 다른 리소스에 대한 정보는 어떠한 것이 있는지. 이러한 모든 정보를 같이 알려주는 기능을 HATEOAS라고 한다.

 

GET /users/123
{
    "id": 123,
    "name": "sparta",
    "links": {
        "self": "/users/123",
        "update": "/users/123",
        "delete": "/users/123"
    }
}

 

 

★ RESTful API 설계 시 고려해야 할 사항들

 

1. Consumer first

• 개발자 중심의 설계방식보다 해당 API의 소비자 입장에서 간단하고 직관적인 API를 설계 해야한다.
• 위에서의 소비자는 엔드유저가 아닌 API를 사용 하고있는 또다른 시스템, 개발자 등을 얘기한다.

2. Make best use of HTTP

• HTTP Method와 Request, Response, Header와 같은 HTTP의 장점을 살려서 개발 해야한다.

3. Request methods

• 최소한 성숙도 모델 Level2로는 사용하여야 한다.

4. Response Status

• 각각의 API 요청에 따라서 적절한 HTTP 상태코드가 전달되어야 한다.
• 성공했다, 실패했다가 아닌 왜 실패하고 성공 하였는지 함께 반환 시켜주어야 한다.

5. No secure info in URI

• URI에는 사용자의 정보를 포함해서는 안된다.

6. Use plurals

• 제공하는 데이터에 대하여 단수가 아닌 복수형태로 쓰는것이 일반적이다.
• 특정 유저를 찾고자 한다면 엔드포인트에 값을 추가한다.

• ex) /user -> /users
• ex) /users/1

 

7. User nouns for resources

• 모든 리소스는 가능하면 동사가 아닌 명사형태로 표시한다.
• API URI만 보고도 어떠한 API인지 파악할 수 있는것이 좋다.

8. For exceptions - define a consistent approach

• 일괄적인 엔드포인트를 사용하는것이 좋다.