RESTful API by 큰돌

Seon Kim·2024년 6월 10일

제대로 이해하는 REST API

REST API란?

일련의 특징과 규칙 등을 지키는 API
Roy Thomas Fielding이 작성한 논문에서 유래했다. https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf

5가지 주요 특징 설명

논문에서는 8가지 특징으로 설명 되었다.
- null style 아키텍처 설계과정이 아무것도 없는 것으로 부터 시작한다는 개념
- 별로 중요하지 않는 개념

1. Uniform-Interface

정의

API에서 자원들은 각각의 독립적인 인터페이스를 가지며 각각의 자원들이 url 자원식별, 표현을 통한 자원조작, Self-descriptive messages, HATEOAS 구조를 가지는 것을 말합니다.
독립적인 인터페이스라는 것은 서로 종속적이지 않은 인터페이스를 말한다.
- 예를 들어 웹페이지를 변경했다고 웹 브라우저를 업데이트하는 일은 없어야 하고 HTTP 명세나 HTML 명세가 변경되어도 웹페이지는 잘 작동해야 하듯이 말이다.

URL 자원식별: identification of resources

자원은 url로 식별된다.
- /product/id에서 id에 1201를 넣어서 요청하면 그 id 값에 대한 정보를 제공해야한다는 원칙

표현을 통한 자원 조작 : manipulation of resources through representations

url 과 GET, DELETE 등 HTTP 표준메서드 등을 통해 자원을 조회 삭제 등 작업을 설명하는 정보를 담는다.
- 어떤 정보를 가져오고 싶다고 해서 url에 getProduct로 표현하면 안된다.
  - get는 http메서드로 표현해야한다.

Self-Descriptive Messages,

HTTP Header에 타입을 명시하고 각 메시지(자원)들은 MIME types에 맞춰 표현되어야한다.
- 예를 들어 json 타입은 application/json으로 명시한다.
- MIME types이란 문서,파일 등의 특성과 형식을 나타내는 표준
  - IETF의 RFC6838에 정의 및 표준화되어 있습니다.
  - ‘font/ttf’, ‘text/plain’, ‘text/csv’ 기타 등등
```
const express = require ('express')
const app = express()
```
  - express라는 모드를 기반으로 만들어졌고, 그 기반으로 만들어진 변수 app을 기반으로 에 담는다.
```
app.get('/good',(req,res) => {
		res.status(200).json({"a" : 1})
})
app,get('/bad',(req,res) => {
		res.setHeader('content-type','application/json');
		res.send("큰돌이")
})
```
  - Self-Descriptive 잘 될때:
    - http get이라는 메소드의 good이라는 path일때, json형태로 a라는 키와 1이라는 value를 보낸다.
    - 기본적으로 json() 는 content-type을 application/json을 할당하고 있어서 따로 설정할 필요가 없다.
  - Self-Descriptive 잘 되지 않을때:
    - http get이라는 메소드의 bad라는 path에서 큰돌이라는 text를 보내는데 setHeader의 content-type을 application/json으로 설정해서 옳지 못한 설정
    - JSON으로도 단순 문자열을 표현할 수 있지만 보통은 type=JSON으로 보낸다라고 했을 때 JSON Array, object를 보내야 하며 단순 텍스트를 보낼 때는 text 타입이라 명시해야 합니다.
```
const server = app.listen(12010 , () => {
			console.log("오늘도 재밌는 CS공부서버 ~ : http://127.0.0.1:12010/good")
})
```
  - 서버를 실행시킨다는 세팅

HATEOAS : Hypermedia as the Engine of Application State

하이퍼링크에 따라 다른 페이지를 보여줘야 하며 데이터마다 어떤 URL에서 원했는지 명시해주어야 하는 것을 말합니다.
보통은 href, links, link, url 속성 중 하나에 해당하는 데이터의 URL을 담아서 표기해야 합니다. rel은 relation으로 링크와 요청한 자원과의 관계를 나타낸다. self 는 해당 자원에 대한 링크 나타냄 detail은 상세한 내용 buyBook 책을 사는 정보를 담고 있을때 사용

독립적인 인터페이스라는 것은 서로 종속적이지 않은 인터페이스를 말합니다.

예를 들어 웹페이지를 변경했다고 웹 브라우저를 업데이트하는 일은 없어야 하고 http 명세나 html명세가 변경되어도 웹페이지는 잘 작동해야 한다.

2. Stateless

HTTP 자체가 Stateless의 성징르 가지고 있어서 HTTP를 이용하는 것 만으로도 만족이 된다. 그리고 REST API를 제공해주는 서버는 세션을 해당 서버 쪽에 유지하지 않는다는 의미를 나타낸다.
RESTAPI로 서버를 만들게 되면 세션 정보를 넣으면 안된다.
- 그래서 Session 방식의 회원관리는 서버에 정보가 남기 때문에 RESTFUL 하지 않다는 뜻이 된다.

3. Cacheable

⚙ HTTP 헤더의 Cache-Control = no-stroe로 하게 되면 캐싱이 안됩니다. 기본적으로 cache-control = public으로 되어있기 때문에 캐싱이 되며 HTTPheader를 기반으로 캐싱 컨트롤을 하는게 중요하다.

HTTP는 원래 캐싱이 됩니다. 아무런 로직을 구현하지 않더라도 자동적으로 캐싱이 됩니다. 새로고침을 하면 304가 뜨면서 원래 있던 js와 css 이미지 등을 불러오는 것을 볼 수 있습니다.
이는 HTTP 메소드 중 GET에 한정되며 ‘Cache-Control: max-age=100’ (100 초) 이런 식으로 한정된 시간을 정할 수가 있으며 캐싱된 데이터가 유효한지를 판단하기 위해 ‘Last-modified’와ㅣ ‘Etag’라는 헤더값을 씁니다. ‘Etag’는 전달되는 값에 태그를 붙여서 캐싱되는 자원인지를 확인해주는 것입니다.

4. Client-Server 구조

클라이언트와 서버가 서로 독립적인 구조를 가져야 합니다.
- 물론 이는 HTTP를 통해 가능한 구조입니다. 서버에서 HTTP 표준만 지킨다면 웹에서는 그에 따른 화면이 잘 나타나게 됩니다.
- 서버는 그저 API를 제공하고 그 API에 맞는 비즈니스 로직을 처리하면 됩니다.
- 마찬가지로 클라이언트에서는 HTTP로 받는 로직만 잘 처리하면 되는 것입니다.

5. Layered System

계층구조로 나눠져 있는 아키텍처를 뜻합니다.
WEB 기반 서비스를 하면 구조 설정 없이 보통 이러한 시스템을 구축하게 됩니다.

Untitled

6. REST API의 URI 규칙

표현을 통한 자원조작을 통해서 REST API의 URI 규칙이 만들어졌다.

동작은 HTTP 메소드로만 해야하고 URL에 해당 내용이 들어가면 안됩니다.
1. PUT=Update, Delete= Delete, POST=Create, GET=Read
2. ‘/books/delete/1’ 이렇게 메소드가 url에 표기되면 안된다.
확장자를 표시하면 안된다.
1. .jpg, .png 등
동사가 아닌 명사로만 표기해야 합니다.
1. “유저가 책을 소유한다.”의 표현할 때
  1. 유저/유저아이디/inclusion/책/책아이디 로 include 보다 inclusion으로 표기해야한다.
2. 유저가 소유한 아파트 조회
  1. /users/{usersid}/aparts
  2. /getAllUsers 식의 동사를 집어넣으면 안된다.
계층적인 내용을 담고 있어야한다.
1. /집/아파트/전세
대문자가 아닌 소문자로만 쓰며 너무 길 겨우에 바를 써야 할 경우 언더바가 아닌 그냥 바를 씁니다.
HTTP 응답 상태코드를 적재적소에 활용합니다. 성공시 200, 리다이렉트는 301 등..

쿼리스트링과 혼합한 url

REST API는 일반적으로 /를 기반으로만 구축되는 것도 있지만, 적절한 쿼리스트링을 혼재해서 쓰기도 합니다.
검색, 페이지네이션, 정렬 등 매개변수가 많거나 복잡할 때 쿼리스트링을 쓰는게 좋습니다.

API 구축 (v1,v2..)

우리가 일반적으로 api를 구축할 때 버전을 이용해서 만드는데 이유는 버전이 업데이트 되었을 때 기존에 사용하던 유저들이 새로운 버전을 바로 사용할 수 없기 때문에 유해기간을 제공하기 위해서 버전을 기입한다.
새로운 버전은 버그가 있을 수 있기 때문에 새로운 버전이 있어도 옛날 버전을 살려둘 수 있기 때문에 버전을 나눠서 사용하다가 안정화가 되었을 때 새로운 버전으로 자체적으로 마이그레이션이 쉬워진다.

Seon Kim

개발 어린이

이전 포스트

RESTful API by 알코

다음 포스트