RESTful API 간단한 API 만들기, Postman 사용법

~ 포스팅 진행 순서  ~

REST, REST API

RESTful

설계원칙

API 구현하기

=> REST, REST API, RESTful의 기본 개념과 간단한 api 만드는 방법 진행

=> RESTful API는 데이터를 표준화된 방식으로 주고 받을 수 있게 해주고, 클라이언트와 서버 간의 명확한 데이터 교환을 가능하게 한다 

API 테스트 - POSTMAN 사용법

 

1. REST(Representational State Transfer) 

1-1. REST 개념

1) HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)를 명시하

2) HTTP Method(POST, GET, PUT, DELETE, PATCH)를 통해

3) 해당 자원(URI)에 대한 CRUD Operation을 적용하는 것을 말한다

 

1-2. REST에서 CRUD란

Create :  데이터 생성(Post)
Read : 데이터 조회(Get)
Update :  데이터 수정(Put, PATCH)
Delete : 데이터 삭제(Delete)

 

1-3. REST 구성요소

1) HTTP URI : 자원(Resource)

2) HTTP Method : 자원에 대한 행위(Verb)

3) HTTP Message Pay Load : 자원에 대한 행위의 내용(Representations)

 

1-4. REST 특징

1) Server-Client(서버-클라이언트) 구조
2) Stateless(무인 상태)
3) Cacheable(캐시 처리 기능)
4) Layered System(계층화)
5) Uniform Interface(일관적 인터페이스)

 

1-5. 장단점

1) 장점 : 

- HTTP 프로토콜의 인프라를 그대로 사용해 REST API 사용을 위한 별도의 인프라를 구축할 필요가 없다

- HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다

- Hypermedia API의 기본을 지키며 범용성을 보장한다

- REST API 메시지가 의도하는 바를 명확히 나타내 의도하는 바를 쉽게 파악할 수 있다

- 여러가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다

- 서버와 클라이언트의 역할을 명확히 분리할 수 있다

 

2) 단점 : 

- 표준 자체가 존재하지 않아 정의가 필요하다

- HTTP Method 형태가 제한적이다

- 브라우저를 통해 테스트할 일이 많은 서비스라면 Header 정보의 값을 처리해야 하므로 전문성이 필요함

- (익스플로러) 구형 브라우저에서 호환이 되지 않아 지원되지 않는 동작이 많음

 

1-6. REST API (Representational State Transfer API)

: REST의 원리를 따르는 API(시스템)

올바르게 REST API를 설계하기 위해서는 지켜야하는 규칙이 존재한다

 

 * REST API 설계 규칙 *

1) URI는 동사보다 명사를 사용 / 대문자보다는 소문자를 사용해야함 

나쁜 예시) https://github.com/minjeong-j/DoingTEST
좋은 예시) https://github.com/minjeong-j/doingtest

 

2) 마지막에 슬래시(/)를 포함하지 않는다 

나쁜 예시) https://github.com/minjeong-j/
좋은 예시) https://github.com/minjeong-j

 

3) 언더바 대신 하이픈을 사용한다 

나쁜 예시) https://github.com/minjeong-j/doing_test
좋은 예시) https://github.com/minjeong-j/doing-test

 

4) 파일 확장자는 URI에 포함하지 않는다

나쁜 예시) https://github.com/minjeong-j/test.jpg
좋은 예시) https://github.com/minjeong-j/test

 

5) 행위를 포함하지 않는다

나쁜 예시) https://github.com/minjeong-j/deletetest/1
좋은 예시) https://github.com/minjeong-j/test/1

 

 

2. RESTful 개념

REST 원리(HTTP를 기반으로 클라이언트와 서버 간에 데이터를 주고받는 아키텍처)를 따르는 시스템 

REST API의 설계 규칙을 올바르게 지킨 시스템을 RESTful하다 말할 수 있다
모든 CRUD 기능을 POST로 처리하는 API / URI 규칙을 올바르게 지키지 않은 API는
REST API의 설계 규칙을 올바르게 지키지 못한 시스템은
REST API를 사용했지만 RESTful하지는 못하다

 

2-1. RESTful API 

각 URL이 리소스(데이터)를 나타내고 HTTP 메소드를 사용해 리소스를 처리한다

 

2-2. HTTP Method (POST, GET, PUT, DELETE, PATCH) : REST 구성요소

POST : 리소스 생성
GET : 리소스 조회
PUT : 리소스 전체 수정
DELETE : 리소스 삭제
PATCH : 리소스 일부 수정

 

 

3. RESTful API 설계 원칙

리소스 기반 설계
HTTP 메소드 사용
Stateless 상태 정보 없음
표준 응답 코드 

 

3-1. 리소스 기반 설계 

: URL은 리소스를 나타낸다 (예시 : /users 사용자 정보 데이터를 의미)

 

3-2. HTTP 메소드 사용 

: 각 메소드는 리소스에 대한 특정 작업을 나타낸다 

 

3-3. Stateless 상태 정보 없음 

: 각 요청은 독립적이고, 서버는 요청 간의 상태를 저장하지 않는다

 

3-4. 표준 응답 코드  

: 성공, 실패 등의 상태를 나타내기 위해 HTTP 상태 코드를 사용한다

 

 

4. API 구현하기

프로젝트 rest-api-example 생성

 

4-1. Express 설치

mkdir rest-api-example
npm init -y
npm install express

 

각 명령어 설명

// mkdir : make directory의 약자, 폴더를 생성할 때 사용하는 명령

// 초기화

// express 설치

 

1) 폴더 생성

mkdir rest-api-example

프로젝트 폴더 생성

mkdir로 빈 폴더 생성

 

2) 초기화

npm init -y

npm init -y으로 초기화하면 package.json 생성

 

3) express 설치

npm install express

express 설치하면 package-lock.jason 생성

 

 

4-2. API 엔드포인트 생성

> server.js 생성

server.js

// server.js
const express = require('express');
const app = express();
app.use(express.json()); // JSON 데이터를 처리하기 위해 필요

// 간단한 사용자 데이터
let users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
];

// GET 요청: 모든 사용자 조회
app.get('/users', (req, res) => {
  res.json(users);
});

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

// POST 요청: 새로운 사용자 추가
app.post('/users', (req, res) => {
  const newUser = {
    id: users.length + 1,
    name: req.body.name,
  };
  users.push(newUser);
  res.status(201).json(newUser);
});

// PUT 요청: 사용자 정보 수정
app.put('/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  if (!user) return res.status(404).send('User not found');

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

// DELETE 요청: 사용자 삭제
app.delete('/users/:id', (req, res) => {
  const userIndex = users.findIndex(u => u.id === parseInt(req.params.id));
  if (userIndex === -1) return res.status(404).send('User not found');

  const deletedUser = users.splice(userIndex, 1);
  res.json(deletedUser);
});

// 서버 실행
const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

 

 

4-3. 코드 분석

server.js GET

1) 사용자 조회

* GET/users 

app.get('/users', ...) : 모든 사용자 목록을 반환

 

* GET/users/

app.get('/users/:id', ...) : 특정 ID에 해당하는 사용자의 정보를 반환

 

server.js POST

2) 사용자 추가

* POST/users

app.post('/users', ...) : 새로운 사용자를 추가

 

server.js PUT

3) 사용자 정보 수정

* PUT/users/

app.put('/users/:id', ...) : 특정 ID의 사용자 정보를 수정

 

server.js DELETE

4) 사용자 삭제

* DELETE/users/

app.delete('/users/:id', ...) : 특정 사용자를 삭제

 

 

4-4. API 테스트

Postman download

https://www.postman.com/downloads/

Download Postman | Get Started for Free

 

 

express 서버를 실행하고 Postman이나 브라우저에서 API 엔드포인트를 테스트해볼 수 있다

node server.js

서버 실행 완료

서버 실행된다는 링크 들어가보면 이래요 여기 말고!!

1) GET : 

http://localhost:3000/users : 사용자 확인

http://localhost:3000/users

> 접속해  GET 요청을 보내면 등록한 모든 사용자 데이터를 볼 수 있다

 

2) POST : 새로운 사용자를 추가해보자

다운로드한 Postman 접속

 

New - HTTP 선택해서 생성

> New workspace 생성 , GET →POST를 선택

 

http://localhost:3000/users에 POST 요청

> request url 입력, Body - raw 선택 - JSON 데이터 입력

{ 
    "name": "코딩" 
}

 

파라미터 정보에 따라 {"name": "Charlie"}와 같은 JSON 데이터를 전송

 

> Send 클릭

> 성공인 경우 201

실패인 경우 400 / 409 comflict

Response 성공

 

http://localhost:3000/users에서 추가된 사용자 확인

http://localhost:3000/users에 접속하면 추가된 사용자를 확인해볼 수 있다

 

 

3) PUT : 특정 사용자의 name 수정

> PUT 선택,

URL 입력 : 예시에서는 http://localhost:3000/users/변경하려는대상ID넘버

ID가 3번인 회원이 대상임

 

Body - raw - JSON 선택 - 변경해줄 이름 입력

{ 
    "name" : "change"
}

name이 코딩인 사람을 change로 바꿔주겠다

> Send 클릭

 

변경 완료

변경된 것을 확인할 수 있다

 

 

4) DELETE : 특정 사용자를 삭제

> DELETE 선택 

URL 입력 :  http://localhost:3000/users/삭제하려는대상ID
Body - raw - JSON

{ 
    "name" : "change"
}

name이 change인 사람을 삭제하겠다

> Send 클릭

 

Response에서 삭제된 회원 정보 뜸

 

삭제 완료

http://localhost:3000/users/3에 접속해보면 삭제 완료

 

5. RESTful API 설계 고려사항

5-1. 명확한 URL 설계 

: 각 URL은 리소스를 나타내며 직관적이어야 함

 

 

5-2. HTTP 메소드의 적절한 사용

: CRUD 작업에 맞는 HTTP 메소드를 사용한다

GET : 데이터 조회

POST : 데이터 생성

PUT : 기존 데이터 수정

DELETE : 데이터 삭제 

 

* 윗 내용 참고) REST에서 CRUD 

Create :  데이터 생성(Post)
Read : 데이터 조회(Get)
Update :  데이터 수정(Put, PATCH)
Delete : 데이터 삭제(Delete)

 

 

5-3. 상태 코드 

: 응답할 때 적절한 HTTP 상태 코드를 반환해야 한다

 

200 성공적인 요청

201 새로운 리소스가 성공적으로 생성됨

404 리소스를 찾을 수 없음

500 서버 오류 발생

 

 

6. github 업로드

소스코드 아래 링크에서 확인 가능

https://github.com/minjeong-j/rest-api-example

GitHub - minjeong-j/rest-api-example: RESTful API - get, post, put, delete