웹 개발 실무 기술 A to Z #1 - A – API 설계 원칙: RESTful API와 GraphQL 비교

웹 개발 실무 기술 A to Z

A – API 설계 원칙: RESTful API와 GraphQL 비교

API(Application Programming Interface)는 웹 애플리케이션의 핵심 구성 요소입니다.
이번 글에서는 RESTful API와 GraphQL의 원칙과 차이점을 깊이 있게 다뤄보겠습니다.

---

1. API 설계의 기본 원칙

API를 설계할 때 중요한 5가지 원칙이 있습니다.

1. 일관성(Consistency): 모든 엔드포인트가 일관된 규칙을 따르도록 설계해야 함
2. 유지보수성(Maintainability): 새로운 기능 추가 시 기존 API를 변경하지 않고 확장 가능해야 함
3. 보안(Security): 인증과 인가를 통해 데이터 보호 필요 (ex. JWT, OAuth 2.0)
4. 성능(Performance): API 요청 수를 최소화하고, 응답 속도를 최적화해야 함
5. 확장성(Scalability): 서비스 성장에 따라 API를 쉽게 확장할 수 있어야 함

API를 설계할 때, RESTful API와 GraphQL이 가장 많이 사용됩니다.
각 방식의 원칙과 차이점을 살펴보겠습니다.

---

2. RESTful API란?

2-1. REST(Representational State Transfer)의 개념

REST는 자원의 상태(Representation)를 HTTP 프로토콜을 통해 전달하는 방식입니다.
RESTful API는 HTTP 메서드(GET, POST, PUT, DELETE)를 이용하여 리소스를 조작하는 방식으로 설계됩니다.

2-2. RESTful API의 주요 원칙

1. 클라이언트-서버 구조: 프론트엔드와 백엔드를 분리하여 개발
2. 무상태성(Statelessness): 각 요청은 독립적으로 처리되며, 서버가 상태를 저장하지 않음
3. 캐싱 가능(Cacheable): 응답 데이터를 캐싱하여 성능 최적화
4. 계층적 시스템(Layered System): 보안 및 로드 밸런싱을 위해 여러 계층으로 나눌 수 있음
5. 일관된 인터페이스(Uniform Interface): API 설계 시 RESTful 원칙을 지켜야 함

---

3. RESTful API 설계 예제

3-1. RESTful 엔드포인트 구조

사용자(User) 데이터를 다루는 RESTful API 예시입니다.

기능 HTTP 메서드 엔드포인트

사용자 목록 조회	GET	/api/users
특정 사용자 조회	GET	/api/users/{id}
사용자 생성	POST	/api/users
사용자 수정	PUT	/api/users/{id}
사용자 삭제	DELETE	/api/users/{id}

---

3-2. Express로 RESTful API 구현

Node.js 기반의 Express 프레임워크를 활용해 간단한 RESTful API를 만들어 보겠습니다.

const express = require("express");
const app = express();
app.use(express.json());

let users = [
  { id: 1, name: "Alice", email: "alice@example.com" },
  { id: 2, name: "Bob", email: "bob@example.com" },
];

// 사용자 목록 조회
app.get("/api/users", (req, res) => {
  res.json(users);
});

// 특정 사용자 조회
app.get("/api/users/:id", (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id, 10));
  if (!user) return res.status(404).json({ error: "User not found" });
  res.json(user);
});

// 사용자 생성
app.post("/api/users", (req, res) => {
  const newUser = { id: users.length + 1, ...req.body };
  users.push(newUser);
  res.status(201).json(newUser);
});

// 사용자 수정
app.put("/api/users/:id", (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id, 10));
  if (!user) return res.status(404).json({ error: "User not found" });

  user.name = req.body.name || user.name;
  user.email = req.body.email || user.email;
  res.json(user);
});

// 사용자 삭제
app.delete("/api/users/:id", (req, res) => {
  users = users.filter(u => u.id !== parseInt(req.params.id, 10));
  res.json({ message: "User deleted" });
});

const PORT = 5000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

이제 http://localhost:5000/api/users에서 RESTful API를 테스트할 수 있습니다.

---

4. GraphQL이란?

4-1. GraphQL 개념

GraphQL은 페이스북이 개발한 API 쿼리 언어로, 필요한 데이터만 요청할 수 있도록 설계되었습니다.

✔️ RESTful API vs. GraphQL 비교

비교 항목 RESTful API GraphQL

요청 방식	여러 개의 엔드포인트 필요	단일 엔드포인트 (/graphql)
데이터 반환	고정된 구조	원하는 데이터만 선택
API 설계 난이도	간단하지만 유연성이 낮음	유연하지만 복잡할 수 있음

---

4-2. GraphQL API 예제

GraphQL 서버를 Express 기반으로 구축해보겠습니다.

GraphQL 설치

npm install express express-graphql graphql

GraphQL 스키마 정의

GraphQL에서는 데이터를 **스키마(Schema)**로 정의합니다.

const express = require("express");
const { graphqlHTTP } = require("express-graphql");
const { buildSchema } = require("graphql");

// GraphQL 스키마 정의
const schema = buildSchema(`
  type User {
    id: ID!
    name: String!
    email: String!
  }
  
  type Query {
    users: [User]
    user(id: ID!): User
  }
  
  type Mutation {
    createUser(name: String!, email: String!): User
  }
`);

let users = [
  { id: 1, name: "Alice", email: "alice@example.com" },
  { id: 2, name: "Bob", email: "bob@example.com" },
];

// GraphQL API 처리 로직
const root = {
  users: () => users,
  user: ({ id }) => users.find(user => user.id == id),
  createUser: ({ name, email }) => {
    const newUser = { id: users.length + 1, name, email };
    users.push(newUser);
    return newUser;
  }
};

const app = express();
app.use("/graphql", graphqlHTTP({ schema, rootValue: root, graphiql: true }));

app.listen(4000, () => console.log("GraphQL Server running on port 4000"));

GraphQL 서버가 실행되면, 브라우저에서 http://localhost:4000/graphql로 접속하여 아래와 같은 쿼리를 실행할 수 있습니다.

query {
  users {
    id
    name
    email
  }
}

---

5. RESTful API vs. GraphQL: 언제 사용할까?

✔️ RESTful API가 적합한 경우

• 단순한 CRUD API 설계가 필요한 경우
• 캐싱이 중요한 경우 (ex: CDN 활용)
• 전통적인 백엔드 시스템과 통합하는 경우

✔️ GraphQL이 적합한 경우

• 클라이언트가 원하는 데이터만 가져와야 하는 경우
• 모바일 환경에서 데이터 전송량을 줄이고 싶은 경우
• 복잡한 관계형 데이터를 한 번에 요청해야 하는 경우

---

6. 마무리 및 다음 글 예고

이번 글에서는 RESTful API와 GraphQL의 개념과 차이점을 살펴보고, 각각의 구현 방법을 소개했습니다.
다음 글에서는 API 인증 및 보안 (JWT, OAuth 2.0) 방법을 다룰 예정입니다.

다음 글 예고: "API 인증 및 보안 – JWT와 OAuth 2.0 활용법" 🚀