API URL의 설계 & 프로젝트 세팅

ERD를 설계한 후에 필요한 것은 API를 큰 틀에서 설계하는 것이다.

API의 세부적인 사항을 처음에 다 정하기는 어렵지만, 데이터베이스와 마찬가지로 큰 틀을 잡아두는 것은 가능하다.

 

API 설계 시 필요한 것

1. API 엔드포인트 설계

2. 요청 데이터, 응답 데이터 설계

이 정보들을 문서화해서 프론트 개발자가 API를 사용하기 쉽도록 돕는 문서를 API 명세서라고 한다.

 

 

API란 ? 

Application Programming Interface

쉽게 말해서 어려운 것은 감추고 보다 쉽게 상호작용할 수 있도록 해주는 것

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

 

 

REST API

REST는 Representational State Transfer의 약자이다.

HTTP를 기반으로 하는 웹 서비스 아키텍처를 의미하며

HTTP 메소드와 자원을 이용해 서로 간의 통신을 주고받는 방법이다.

 

 

API Endpoint

REST API에서 API Endpoint는 해당 API를 호출하기 위한 HTTP 메소드, URL을 포함한다.

 

 

HTTP 메소드

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

아래 5가지 메소드는 CRUD(생성, 조회, 갱신, 삭제) 4가지에 대응된다.

1. GET : 조회
2. POST : 생성
3. PUT : 갱신(전체)
4. PATCH :갱신(일부)
5. DELETE : 삭제

POST는 새로운 자원의 생성도 있지만,

클라이언트가 특정 정보를 서버로 넘기고 그에 대한 처리를 요청하는 것을 전부 POST로 처리 가능하다.

 

---

RESTful API Endpoint의 설계

아래의 규칙에 따라 설계가 가능하다.

 

1. URI에 동사가 포함되면 안된다.

2. URI에서 단어의 구분이 필요한 경우 -(하이픈)을 이용한다.

3. 자원을 기본적으로 복수형으로 표현한다.

4. 단 하나의 자원을 명시적으로 표현하기 위해서는 /users/id와 같이 식별 값을 추가로 사용한다.

5. 자원 간 연관 관계가 있을 경우 이를 URI에 표현한다.

 

 

회원 가입, 로그인, 탈퇴

1. 로그인

로그인의 주체가 되는 대상은 사용자이므로

url 상에 users가 들어가는 것은 쉽게 감이 온다.

 

우선 클라이언트가 로그인에 필요한 정보를 서버로 넘겨 로그인에 대한 처리를 요청하는 것이니

POST로 설계를 해야 한다.

 

회원 가입 역시 새로운 사용자의 생성이기 때문에 POST /users 로 표현이 가능하다.

따라서 회원 가입의 경우가 있기 때문에

로그인을 POST /users로 표현하기 힘들다.

이런 경우에는 너무 타이트하게 RESTful한 설계를 따르려고 하지 않아도 된다.

 

POST /users/login -> 이정도면 괜찮다.

위처럼 HTTP 메소드, 필요한 자원에 대한 명시를 한 URI를 합쳐 API Endpoint라고 한다.

 

웹 서비스를 하는 서버의 도메인 주소가 https://claire.com 일 경우 

POST https://claire.com/users/login 이렇게 요청을 할 경우 로그인이 되는 것이다. 

 

 

 

2. 회원 가입

POST /users 로 해도 되지만

기능 요구 사항에서 회원 가입 외에 사용자가 새로 추가가 되는 경우가 있다면,

해당 API와 구분을 해야 한다.

 

Q. 회원 가입은 유저 한 명이 생기는 건데, POST /users/id 아닌가요 ?

POST /users/id의 형태로 설계를 하려면, 해당 유저를 식별할 값이 존재해야 하는데

회원 가입 이후에서야 해당 유저가 생성이 되기에, 유저를 식별할 값이 API 호출 시점에는 없다.

따라서 이런 경우는 위와 같은 설계가 불가능하다.

 

 

 

3. 회원 탈퇴

DELETE /users 로 설계가 가능하다고 생각이 들지만 !

요구 사항이 회원 탈퇴 시 곧바로 데이터베이스에서 삭제가 아니라, 비활성 계정으로 만들고, 추후 계정 복구를 고려한다면

DELETE로 설계하면 안된다.

 

이런 경우 데이터베이스에서 사용자 테이블의 status를 active에서 inactive로 변경하는 것이기에

일부 수정인 PATCH를 활용해야 한다.

 

PATCH /users

그러나 이 경우 회원 정보 수정 API까지 고려해서 설계를 해야한다.

회원 정보 수정 API 역시 닉네임 등 일부 정보만 수정하는 것이기 때문에

PATCH를 사용하며, PATCH /users로 설계가 가능하다.

 

이런 경우,

회원 정보 수정은 PATCH /users/id 로 특정 유저의 정보 수정임을 명시적으로 표현하고,

회원 탈퇴는 PATCH /users 로 표현할 수 있다.

 

 

 

이렇듯, API 설계에는 절대적인 정답은 없고

위에서 나열한 5개의 규칙을 지키되,

요구 사항에 따라 피치 못한 경우는 무조건 위 규칙을 따르지 않아도 된다.

결국 프론트엔드 개발자분들이 API 설계를 보고 쉽게 무슨 API인지 이해하면 되는 것!

 

---

 

 

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

예를 들어

교과목이 한 명의 사용자(교사)가 여러 개의 교과목을 강의할 수 있다고 하고,

교사와 교과목이 1 : N 관계인 경우

이런 상황에서 교과목의 목록을 조회하는 API를 설계한다고 가정

 

교과목은 교사와 1 : N 관계를 가지므로 아래처럼 설계할 수 있다.

편의를 위해 사용자는 오로지 교사만 있다고 가정

/users/subjects

 

이런 식으로 교사가 여러 개의 과목을 강의하기에

계층 관계는 교사 다음 교과목으로 잡고,

uri 상에 교사가 계층 관계 상 더 우선이 된다는 것을 표현할 수 있다.

 

 

만약, 특정 교사의 교과목 목록을 보고 싶다면?

/users/id/subjects

로 설계가 가능하다.

 

교과목 하나 단건 조회 API를 설계한다면 ?

특정 교사의 특정 교과목이 더 의미가 잘 전달이 된다    ->     /users/id/subjects/id

그저 특정 교과목이 더 의미가 잘 전달이 된다     ->     /users/subjects/id

 

N : M 관계

게시글과 해시태그가 예시이다.

이런 경우 계층 관계를 한 눈에 보기가 힘들다.

비즈니스 로직상 더 중요한 대상을 계층 관계에서 앞에 두는 방법이 있다.

게시글과 해시태그 중 직감적으로 해시태그가 부수적이고, 게시글이 서비스에서 더 중요한 역할을 한다는 것을 알 수 있다.

/articles/hash-tag

 

이렇게 설계가 가능하다.

 

이처럼 API 설계에서도 기획의 요구 사항이 영향을 끼치므로

반드시 PM, 프론트 개발자들과 많은 소통을 하여 설계를 하는 것이 좋다.

 

---

세부적인 API 설계

API 설계를 할 때 고려해야 할 것들

1. path variable

2. query string

3. request body

4. request header

 

위 4개 중 API endpoint에 포함이 되는 것은 1번 뿐이다.

 

API Endpoint는 간략하게 ( 이런 역할을 하는 API이다 ) 정도만 알려주는 것이다.

 

Q. 회원 가입이란, 회원 정보를 새로 저장하는 건데, 무슨 정보를 저장하나요 ?

엔드 포인트 하나만으로 실제 동작 수행에 필요한 정보를 표현할 수 없다.

이런 경우 바로 위의 4가지를 사용하게 된다.

 

Path Variable

게시글 하나 상세 조회 API 를 예로 들었을 때,

곧바로 단건 조회, 즉 GET에 단건 조회라는 것은 빠르게 알 수 있다.

 

여기서 어떻게 특정 게시글임을 서버에게 전달이 가능할까 ?

어떻게 서버에게 원하는 게시글을 식별할 수 있는 데이터를 넘길 수 있을까 ?

 

이런 경우 path variable을 사용한다.

단 하나, 특정 대상을 지목할 때

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

 

GET https://claire.com/users/articles/4

여기서 4가 데이터베이스 상에서 게시글의 기본키이다.

 

 

실제 API 명세서에서는 아래처럼 표현한다.

GET /users/articles/{articleId}

 

{ } (중괄호)로 감싸는 부분은 path variable을 의미하고,

그냥 id 보다는 articleId처럼 더 명확하게 표시해주는 것이 좋다.

 

 

단어 구분을 -를 사용해서 한다고 했으니,

GET /users/articles/{article-id}

로 해도 된다.

 

 

Query String

게시글 중 이름에 claire가 포함된 게시글들을 조회하려고 할 때,

1개가 될 수도 있고 여러 개가 될 수도 있다.

 

따라서 단 하나만 조회하는 path variable을 사용하는 것은 아니고,

query string을 활용하는 것이다.

 

쿼리 스트링은 보통 검색 조회 때 사용이 되며 따라서 GET 요청에서 사용이 된다.

GET /uesrs/articles?name=claire

위처럼 name이 claire라는 것은 전달 할수도 있고,

 

전달할 정보가 여러 개일 경우 아래와 같이

GET /users/articles?name=claire&group=umc

&를 통해 쿼리 스트링으로 전달하려는 값을 여러 개 연결할 수도 있다.

 

주의할 점은, 쿼리 스트링은 API 엔드 포인트에 포함이 되지 않기 때문에

엔드 포인트 자체는 GET /users/articles 로 설계해야 한다.

 

 

 

Request Body

POST는 조회가 아닌, 생성을 위해 사용하기도 하기 때문에

URL에 해당 정보들을 노출하는 것은 굉장히 위험할 수 있다.

 

따라서 URL에 노출이 되지 않고, request body에 해당 데이터를 담을 수 있으며,

보통 json의 형태 혹은 form-data 형태로 보내게 된다.

 

예를 들어 회원 가입시 아래의 정보가 필요하다고 할 때,

1. 이름

2. 전화번호

3. 닉네임

 

request body에 위의 정보를 json으로 담아서 서버로 전송하게 된다.

{
	"name" : "클레어",
    "phoneNum" : "010-1111-2222",
    "nickName" : "claire"
}

 

 

Request Header

서버에 전송 시 메타데이터,

즉 전송에 관련된 기타 정보들이 담기는 부분이다.

 

body에 담기는 데이터의 형식이 json인지, 아니면 form-data인지를 담기도 하고

혹은 데이터를 담을 수도 있다.

 

대표적으로 로그인이 되었다는 것을 알려주기 위한 토큰을 헤더에 담기도 한다.

 

 

 

 

---

API 설계 예시

닉네임 변경 ( 사용자 정보 변경 )  API에 대한 설계

 

API Endpoint

PATCH /users/{userId}

 

 

Request Body

{
	"nickname : claire"
}

 

 

Request Header

Authorization : accessToken (String)

 

accessToken은 로그인 된 사용자가 나 로그인된 상태야 ! 하고 알려주는 것으로

보통 Authorization이라는 키에 대한 값으로 헤더에 담아서 서버로 보낸다.

 

 

Query String

필요 없다.