restful api 정리

api의 다향한 형식중 가장 보편적인! restful api

 

요청방식과 응답방식이 정해졌다!\

 

CRUD는

POST,GET,PUT,PATCH,DELETE의 5가지 method가 있다.

 

중요한 원칙. 

URI에서 어떤 자원에 대한것인지만 표현. (명사적)

어떠한 작업을 하는지는 (method는) URI상 표현하지 않는다.

 

먼저 많은 정보를 보낼필요가 없는(body를 쓰지 않는!)

GET, DELETE가 있다.

그리고 POST,PUT,PATCH는 body를 쓴다.

 

[GET]에서 특정조건으로 필터링하려면 쿼리파라미터를 사용하면 됨.

그래서 현장에선 부하를 막아야함으로 페이징같이 필터를 써야함.

 

유용한 원칙

"HATEOAS"  : Hyperdia As The Engine Of Application State

각 요청의 응답에다가 쓸수있는 다른 요청들의 정보를 포함시키는 원칙!

-> DX 좋아짐, 다른요청 세부사항 변해도 클라이언트측에서 참조하면 해결됨.

 

resource들의 상하관계는 URI로 표현할 수 있다.

 

 

[POST] 

 

 

[PUT][PATCH]

put은 특정항목의정보를 갈아엎을때 사용.

patch는 특정항목의 특정값만 가볍게 수정할때 사용.

put patch오용하면 큰일남. patch하려고 하나필드만 넣었는데 실수로 put 으로 했으면 나머지필드값 null로 변해버리는 대참사!

 

 

----------------------------

restful api 의 또다른 특성은 stateless!!

그래서 클라이언트는 요청을몇번을 반복하든 필요한 모든 내용을 포함해야함.

 

'멱등성(idempotent)' : 클라이언트가 같은 요청을 몇번을 보내든 언제나 같은답이 와야함. (실제데이터가 바뀌지 않는다면_) - GET,DELETE,PUT은 멱등성을 가져야 함. 왜?? => 

 

즉 클라이언트와 서버는 서로에 대해 기억하지 않는게 좋다는것.

다만 자기가 어떤 응답을 보내고 받았는지는 기억하는게 좋을수도있음.  (Cachability, 캐싱!!) -> 낭비 줄일 수 있음.

 

 

 

추가로 지피티선생의 조언

 

1. HTTP Status Code 정리

• 2xx (성공): 요청 성공 시 주로 200(OK), 201(Created), 204(No Content) 등을 어떻게 구분해서 사용하는지.
  ->>200은 요청success.
  ->>201은 새로운 resource가 생성되었을때 (created)
  ->>204는 요청은 성공했지만 추가적으로 더 보낼 내용(body)이없을때 (no content)
• 3xx (리다이렉션): 리다이렉트의 필요성과 동작 방식.
• 4xx (클라이언트 오류): 400(Bad Request), 401(Unauthorized), 403(Forbidden), 404(Not Found) 등 의미 명확히 알기.
  ->>400은 요청파라미터가 잘못되었거나 필요정보 누락 시
  ->>401은 인증필요한 요청인데 인증정보가없거나 잘못돼었을때
  ->>403은 인증됐지만 해당리소스 권한없음
  ->>404는 낫파운드!
• 5xx (서버 오류): 500(Internal Server Error), 503(Service Unavailable) 등.
  ->>500서버에서 처리도중 예상치못한 오류가있을때
  ->>503은 과부하 or 보수중

 

 

 

2. HTTP Header와 Content Negotiation

• Content-Type / Accept: REST에서 JSON을 많이 쓰지만, XML을 요청하는 클라이언트도 있을 수 있으니 이에 대한 처리(예: Accept: application/json, application/xml)를 어떻게 하는지.
• Authorization 헤더: 보안(인증/인가) 방식을 어떻게 적용하는지(JWT, OAuth2 등).
• ETag / Last-Modified: 리소스의 버전을 식별해 캐싱 및 중복 작업 방지(Optimistic Lock) 등에 사용하는 방법.

이런 헤더들을 사용하는 이유와 활용 방법을 알면 “RESTful한 API 설계에서 어떤 부분들을 신경 쓰나?”라는 질문에 유용하게 답변할 수 있습니다.

“RESTful API에서 Content-Type, Accept, Authorization 헤더 등은 왜 필요하며,
클라이언트가 JSON 또는 XML을 원할 때 어떻게 대처하면 좋을까요?”

일단 header부분은 서버 클라이언트가 교환하는 부가정보를 담는것
* Content-Type : 서버 혹은 클라이언트가 보내는 데이터형식 명시 ex > application/json

* Accept : 클라이언트가 응답으로 받고싶은 데이터형식을 서버에 알리는 형식.
* Authorization : 인증 토큰(JWT, OAUTH, 토큰)을 담아보냄.
* ETag / If-None-Match: 캐싱 전략 및 변경 감지(조건부 요청)에 사용됩니다

---

 

3. URI 설계 시 주의할 점

• 명확한 자원(Resource) 표현: 복수형 사용 예) /users, /posts
• 계층 구조: 예) 유저가 작성한 게시글 /users/{userId}/posts
• 버전관리: URI에 버전을 포함시키는 방식 예) /v1/users, 혹은 헤더로 버전을 구분하는 방식(예: Accept: application/vnd.myapp.v1+json) 등

“RESTful API 디자인 시 어떤 기준으로 URI를 정하나요?” 같은 질문에서 중요한 부분입니다.

면접에서 나올 수 있는 질문 예시

“RESTful API를 설계할 때 어떤 규칙에 따라 URL(URI)을 정하나요?
예를 들면, 어떤 경우에 복수형을 쓰고, 어떤 경우에 URI에 버전을 붙이고,
혹은 /users/{userId}/posts 같은 중첩 경로를 어떻게 처리하나요?”

예시 답변

“URI는 자원을 표현해야 하므로, 일반적으로 복수형 명사를 사용합니다. 예를 들어 유저 자원은 /users, 게시글 자원은 /posts처럼 표현합니다. 특정 유저에 대한 상세 정보를 가져올 땐 /users/{userId}, 그 유저의 게시글은 /users/{userId}/posts 처럼 계층 구조를 적용합니다.

버전 관리는 보통 크게 두 가지 방식이 있습니다:

1. URI에 버전을 붙이기: 예) /v1/users, /v2/users
2. 헤더로 구분: 예) Accept: application/vnd.myapp.v1+json  (얘는 뭘까?  -> )

규모가 커지거나 호환성 이슈가 생길 때는 버전을 명확히 구분해줘야 합니다!.”

 

4. Query Parameter와 Path Variable

• 특정 리소스 식별: /users/{userId} 처럼 Path Variable 활용
• 조건 필터링: GET /users?age=30&gender=male 처럼 Query Parameter 활용
• 페이징 처리: GET /users?page=2&size=10

RESTful하게 설계할 때 “URI vs Query Parameter”를 구분하는 이유를 설명할 수 있어야 합니다.

면접에서 나올 수 있는 질문 예시

“GET 요청에서 특정 자원을 식별할 때는 Path Variable을 쓰고,
필터링을 하거나 페이징 처리를 할 때는 Query Parameter를 쓴다고 했는데,
이 둘을 어떻게 구분하고 활용하나요?”

예시 답변

“Path Variable (/users/{userId})은 특정 자원을 식별할 때 사용합니다.
GET /users/123 이라면 userId가 123인 사용자를 정확히 찾아와야 하죠.

한편, Query Parameter (?key=value)는 주로 검색, 필터링, 정렬, 페이징 등에 사용합니다.
예컨대 GET /users?page=2&size=10는 사용자의 2페이지, 10개씩 가져오겠다는 의미입니다.

정리하면 ‘고유 아이디’를 통한 자원 접근에는 Path Variable을,
‘조건(필터/페이징/정렬/검색)’을 위한 요청에는 Query Parameter를 사용하면 됩니다.”

---

6. 보안(인증, 인가)

• Stateless한 특성상 세션이 아닌 토큰 기반 인증(JWT, OAuth) 등으로 진행하는 경우가 많음.
• HTTPS(TLS/SSL) 이용해 암호화하는 것은 사실상 필수.

REST API는 보통 세션을 서버 측에 저장하지 않는 방향으로 구현한다는 점을 강조하면 좋습니다.

면접에서 나올 수 있는 질문 예시

“RESTful API에서 세션 대신 토큰 기반 인증을 사용한다는데,
그 이유와 어떤 토큰 방식을 쓰는지 설명해주세요.”

예시 답변

“RESTful API는 Stateless를 지향하므로, 서버는 클라이언트 상태를 세션으로 저장하지 않는 것이 원칙입니다.
대신 토큰 기반 인증을 사용해서 클라이언트가 매 요청마다 자신의 인증 정보를 보내도록 합니다.

대표적으로 **JWT(JSON Web Token)**가 널리 쓰이는데, 클라이언트는 Authorization: Bearer <JWT> 헤더를 포함해 요청합니다. 서버에서는 이 JWT를 검증해 유효하면 권한을 인정해줍니다. 이렇게 하면 서버가 세션을 저장하지 않아도,
여러 서버 간 확장(스케일 아웃)이 용이하고, Stateless 특성을 유지할 수 있습니다.”

---

 

7. 멱등성(Idempotent)과 안전(Safe) 메서드

• 멱등성: 같은 요청을 여러 번 보내도 서버 상태가 변하지 않는 성질 (GET, DELETE, PUT은 멱등성을 가져야 함).
• 안전(Safe) 메서드: 서버의 리소스를 변경하지 않는 메서드 (GET, HEAD 등).

구체적으로 “PUT이 멱등해야 한다”는 말이 어떤 상황에서 중요한지(결제 API 같은 곳에서 중복 요청 방지) 이야기해주면 좋습니다.

면접에서 나올 수 있는 질문 예시

“PUT과 DELETE가 멱등하다는 말이 무슨 뜻인지,
그리고 왜 이런 특성을 가지는 게 중요한지 설명해주실 수 있나요?”

예시 답변

“**멱등성(Idempotent)**이란 ‘동일한 요청을 여러 번 보내도 결과가 달라지지 않는 성질’을 말합니다.
예를 들어 PUT은 특정 리소스를 완전히 덮어쓰는 것이므로, 5번 연속 PUT을 해도 최종 결과는 동일해야 합니다.
DELETE도 마찬가지로 한번 삭제된 리소스를 다시 삭제해도 결과(삭제됨)는 달라지지 않으므로 멱등합니다.

이는 클라이언트가 네트워크 문제 등으로 동일 요청을 중복으로 전송했을 때,
데이터 불일치나 예측 불가능한 동작이 일어나지 않도록 하는 데 중요합니다.

한편, Safe 메서드는 서버의 상태를 변경하지 않는 메서드(예: GET, HEAD)를 가리킵니다.”

 

 

8. HATEOAS (Hypermedia as the Engine of Application State)

면접에서 나올 수 있는 질문 예시

“HATEOAS가 무엇이며, 실제로 어떻게 적용되나요?
HAL 등 하이퍼미디어 포맷도 들어보셨는지요?”

예시 답변

“HATEOAS는 Hypermedia As The Engine Of Application State의 약자로,
RESTful 원칙 중 하나인 **‘서버가 응답을 줄 때, 해당 리소스와 연관된 다른 액션의 링크도 함께 담아주자’**는 개념입니다.

 

예시를 들면, GET /users/1 요청에 대한 응답이 다음과 같을 수 있습니다:

{
  "userId": 1,
  "name": "Tom",
  "links": [
    { "rel": "self", "href": "/users/1" },
    { "rel": "posts", "href": "/users/1/posts" }
  ]
}

이렇게 하면 클라이언트는 문서나 별도 가이드 없이도,
“이 사용자의 게시글을 가져오려면 /users/1/posts에 GET 요청을 하면 된다”는 것을 알 수 있습니다.

이러한 방식은 **클라이언트 개발자 경험(DX)**을 좋게 만들고,
API 변경사항에 대해서도 유연하게 대응할 수 있게 해줍니다.”