API 설계하기

studychan·2026년 3월 25일

SpringBoot 공부

목록 보기
1/2

API?

api는 다들 일반적으로
"프론트엔드와 백엔드가 데이터를 어떻게 주고받을지 정한 규칙"을 말한다.

맞긴한데.. 뭔가 애매해..
더 자세하게 생각해보자!

API(Application Programming Interface)에서

  • Interface?

    자판기를 떠올려봐라!
    음료수 뽑아 먹을 때 우리는 그냥 돈 넣고 버튼을 누르지,
    자판기 내부가 어떻게 생겼는지, 어떻게 돌아가는지 생각 안한다.

즉, interface는 "자판기의 조작판"이다.
어려운 것은 감추고 쉽게 상호작용 할 수 있도록 해주는 것!

그래서 API는 애플리케이션을 프로그래밍할 때, 쉽게 할 수 있도록 해주는 도구들을 말한다.

API를 설계 시 필요한 것들

  1. API Endpoint(API 주소)의 설계
    • 데이터가 오가는 주소를 말한다
      ex) POST /api/articles (게시글 생성용 주소)
  2. 요청 데이터, 응답 데이터의 설계
    • 요청 데이터: 프론트엔드가 백엔드로 보내는 화물
      ex) {"title": "가입인사", "content": "안녕하세요"}
    • 응답 데이터: 백엔드 처리가 끝나고 프론트엔드에 보내는 결과 보고서
      ex) {"status": "success", "article_id": 15}

프론트엔드 측에서 데이터를 어디로, 어떤 형식으로 보내야 할지 알 수 있도록 설명서가 필요하다.

설명서 내용: 게시글을 등록하려면 /api/articles 주소로 제목과 내용을 JSON형태로 보내라. 그러면 내가 성공여부와 생성 글 번호를 돌려주겠다"

이 설명서를 API명세서 라고 부른다.

REST?

REST: Representational State Transfer의 약자

"HTTP를 기반으로 하는 웹 설계 가이드라인, 아키덱처" 를 말한다

쉽게 말해서, 개발자들마다 API주소, 요청방식을 짜는 것이 다를텐데
그러지말고 "딱 보면 알 수 있도록 일관된 규칙을 쓰자"고
합의한 틀이다.

REST의 핵심 2가지

  1. 자원은 URL로 표현한다.

    • 자원: 명사 자체이다. ex) 회원(User), 댓글(Comment), ...
    • URL: 자원의 위치를 식별하는 문자열

    즉, GET /getUsers가 아니라 GET /users처럼 써야한다.

  2. 행위는 HTTP로 표현한다.

    • URL로 대상을 명확히 지정했으니, 그 대상에게 '무엇을 할지'는
      HTTP 메서드에 맡긴다.

HTTP 메서드 (5가지)

: REST 방식으로 통신 할 때 필요한 작업을 표시하는 방법

1. GET (데이터 조회) - 멱등성 O

  • 동작: 게시글을 100번 조회한다고 해서 조회수 로직을 제외하면 게시글 본문 데이터 자체는 변하지 않는다.

  • 데이터 전달: URL 끝에 붙는 쿼리 파라미터를 쓴다.
    ex) /users?name=kim

  • 팩트: 누구나 URL을 볼 수 있어서 비밀번호 같은 민감정보는 절대로 주면 안된다. Request Body를 통해서 전달할 수는 있지만 Body를 무시하고 버려버리는 곳이 많아서 쓰지 않는 것이 좋다.

2. POST (데이터 생성/처리) - 멱등성 X

  • 동작: '결제하기'버튼을 두 번 누르면? 결제가 두 번 진행된다. 즉, 요청마다 서버의 상태, 데이터가 변한다.

  • 데이터 전달: 민감하지 않은 정보는 쿼리 파라미터로 담고, 민감정보는 Request Body에 담아서 데이터를 전달한다.

  • 팩트: 주로 데이터를 생성,업데이트 하며, 특히 정보를 서버로 넘기고 그에 대한 요청을 처리한다.

3. PUT ( 데이터 전체 덮어쓰기) - 멱등성 O

  • 동작: A,B가 있는 상태에서 C라는 데이터를 PUT으로 100번 보내면 최종 결과는 무조건 C 하나뿐이다.

  • 팩트: 수정이 아니라 '완전한 교체' 이다. 기존 데이터가 없다면 생성한다.

4. PATCH (데이터 부분 수정) - 멱등성 X

  • 동작: PUT과 달리 원하는 부분만 콕 집어서 바꾼다.
    예를 들어, "나이를 +10 해라" 라는 PATCH요청을 5번 보내면 나이가 50살 늘어난다.

  • 팩트: PATCH 메서드를 지원하지 않는 서버일 경우, POST를 사용한다.

5. DELETE (데이터 삭제) - 멱등성 O

  • 동작: 데이터를 삭제한다. 데이터를 1번이든 10번이든 삭제를 하면 "데이터가 없는 상태"로 유지된다.

  • 팩트: Hard Delete던, Soft Delete던 프론트엔드 입장에서는 그냥 "삭제 성공"으로 같아서 상관없다.

RESTful한 API 설계 규칙

위에서도 말했던 내용이다.

  1. URL에 동사가 포함이 되어선 안된다.
  2. URL에서 단어의 구분이 필요한 경우 '-'를 이용한다.
    ex) /api/v1/user-profiles
  3. 자원은 기본적으로 복수형으로 표현한다.
  4. 단 하나의 자원을 명시적으로 표현하기 위해서는 /users/id와 같이 식별 값을 추가로 사용한다.
  5. 자원 간 연관관계가 있을 경우 URL에 표현한다.

리소스 간 연관관계가 있는 경우

예를 들어 교사와 교과목이 1:N 관계일 때,

  • 교과목의 목록을 조회하는 API를 설계한다고 가정해보자.

    /users/subjects 처럼 교사 다음 교과목으로 잡고, URI상에 교사를 상위에 있다고 표현할 수 있다.

  • 특정 교사의 교과목 목록을 조회하는 API를 설계해보자.

    /users/id/subjects 으로 설계 가능

  • 교과목 하나 단건 조회 API를 설계해보자.

    특정 교사의 특정 교과목을 말한다면? /users/id/subjects/id 이며,
    그저 특정 교과목을 말한다면? /users/subjects/id 으로 설계 가능

게시글과 해시태그가 N:M 관계일 때,

어떤 대상을 앞에 둘 지 난감하다...

그래서 비즈니스 로직상 더 중요한 대상을 계층 관계에서 더 앞에 두는 것이 일반적이다!

게시글이 서비스에서 더 중요한 역할을 하기에
/articles/hash-tag 으로 설계 가능

세부 API 설계

그러면 대충 어떻게 설계하면 되는지 파악은 되었다.
그런데..

예를 들어, 회원가입을 하는 상황이다.
이때 EndPoint는 POST /auth/users 정도로 생각할 것이다,,

하지만 회원가입을 한다는 것은 회원정보를 새로 저장하는 것인데
"회원정보는 어디에 담아서 주는거지?"

이런 경우에 아래의 4개를 고려하면서 api를 설계해야 한다.

  1. Path Variable (api EndPoint에 포함됨)
  2. Query Parameter
  3. Request Body
  4. Request Header

Path Variable

우리가 "특정" 게시글을 조회하려고 할 때,
서버에서는 어떻게 "원하는 게시글을 식별할 수 있는 데이터"를 넘기는 것일까?

이럴 때 바로 Path Variable을 사용한다.

즉, /users/articles/id 처럼 id에 게시글 식별값을 넣어서 전달하게 된다.

그래서 실제로는
GET https://umc.com/users/articles/4 처럼 작성할 수 있다.
4는 DB에서 게시글의 Primary Key이다.

API 명세서에는
GET /users/articles/{article-id} 처럼 표현할 수 있다.

Query Parameter

단 하나만 조회하려면 Path Variable을 사용하고,
하나 혹은 여러개를 조회하려면 Query Parameter를 사용한다.

GET /users/articles?name=umc&owner=mark

  • 팩트: Query Parameter는 API EndPoint에 포함되지 않는다.

Request Body

위에서 언급했다시피, POST방식을 쓸 때 민감정보는 URL에 포함시키는 것은
너무 위험하다. 그래서 우리는 Request Body에 민감정보를 담게되고,
일반적으로 데이터는 json형태 or from-data형태로 전달하게 된다.

json형태의 데이터?
{
"name" : "김주헌",
"phoneNum" : "010-1111-2222",
"nickName" : "mark",
}

Request Header

여기에는 전송에 관련된 정보들이 담기게 된다.
Request Body의 형식이 무엇인지(Content-Type), 요청을 어디서 보냈는지 (origin) 등등..

Authorization : Bearer {accessToken}
accessToken은 로그인된 사용자가 "나 로그인된 상태야~" 라고 알려주는 표시이다.

주로 API 명세서는 노션 or Swagger를 이용하여 제작한다.

노션의 경우
배포전에 프론트엔드가 api현황을 확인 가능하지만, 일일히 api 명세서를 업데이트 해야한다.


Swagger의 경우
개발이 끝나면 바로 반영되지만, 배포전까지 프론트엔드가 api현황을 확인 불가능하다.

profile
studychan
꾸준히 성장하는 1인자
다음 포스트

SpringBoot에 대하여

0개의 댓글