🖤 UMC 서버 6주차 스터디 - API URL의 설계 & 프로젝트 세팅 🖤

 

 

 

1.  API ( Application Programming Interface )

 

1 ) API의 정의

API는 말 그대로 Application Programming을 할 때 사용되는 Interface를 의미한다

(위키피디아에 따르면..)

Interface는 서로 다른 두 개의 시스템, 장치 사이에서 정보나 신호를 주고받는 경우의 접점이나 경계면을 의미한다

더 자세히 설명하자면, 특정 동작을 수행하는 복잡한 프로세스를 Interface를 통해 캡슐화 혹은 추상화하여 숨기고

다른 장치와 쉽게 상호작용할 수 있도록 하는 것이다

예시 ) python의 print 함수, JS의 console.log 함수

 

2 ) REST API

REST : Representational State Transfer

REST API는 HTTP를 기반으로 하는 웹 서비스 아키텍처이자

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

더 쉽게 말하자면 체계적인 HTTP 통신을 위한 일종의 규칙을 말한다

 

3 ) API Endpoint

REST API에서 API Endpoint는 HTTP 메소드 + URL 을 의미한다

예시 ) GET  https://sosoeunii.tistory.com/users

 

4 ) HTTP 메소드

HTTP 메소드 : HTTP 통신할 때 필요한 작업을 REST 방식으로 표시한 방법

가장 대표적인 HTTP 메소드 5가지

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

* POST는 새로운 자원의 생성과
   클라이언트가 특정 정보를 서버로 넘기고 그에 대한 처리를 요청했을 때의 처리를 담당한다

 

5 )  RESTful API Endpoint 설계

 

REST API 규칙을 따르면서 API EndPoint( HTTP 메소드 + URI )를 설계하는 방법을 알아보자

기본 규칙

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

 

회원 가입, 로그인

 

회원가입 - 새로운 사용자의 생성 -> POST

POST /users

 

로그인 - 사용자(클라이언트)가 로그인에 필요한 정보를 서버로 넘겨 로그인에 대한 처리 요청 -> POST

이때 POST /users 는 회원가입 API EndPoint와 겹치므로 아래와 같이 쓴다

POST /users/login

* RESTful한 API를 너무 빡빡하게 따를 필요는 없다

 

회원 정보 수정, 회원 탈퇴

 

회원 탈퇴 - soft delete -> PATCH(status를 active => inactive)

PATCH /users

 

회원 정보 수정 - 특정 사용자의 정보를 일부 수정 -> PATCH

PATCH /users/id

* 이때 id는 정보 수정하려는 특정 사용자를 구분해주는 식별자

 

 

🖤 리소스 간 연관관계가 있을 경우

 

[ 1 ]  1 : N 관계

예를 들어 한 명의 교사(사용자)가 여러 개의 교과목을 강의할 수 있는 경우

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

 

응용 1. 전체 교과목의 목록을 조회하는 API

 /users/subjects

계층 관계를 users(교사) 다음 subjects(교과목)으로 잡음으로써

uri 상 교사가 계층 관계상 우선이 된다는 것을 표현한다

 

응용 2. 특정 교사의 교과목 목록을 조회하는 API

 /users/id/subjects

'특정' 교사의 교과목 목록이므로 users 뒤에 식별자 id를 넣어준다

 

응용 3. 교과목 하나 단건 조회 API

* 특정 교사의 특정 교과목이 의미 전달이 더 잘 되는 경우

/users/id/subjects/id

 

* 특정 교과목이 의미 전달이 더 잘 되는 경우

/users/subjects/id

 

 

[ 2 ]  N : M 관계

N : M 관계에서는 어떤 걸 계층 관계상 우선으로 두어야 할지 판단해줘야 한다

 

( 예시 ) 게시글과 해시태그 - N : M 관계

/articles/hash-tags

/hash-tags/articles

둘 중 어떤 것을 사용해야 할까요?

 

비즈니스 로직상 게시글이 해시태그보다 서비스에서 더 중요한 역할을 하기 때문에

/articles/hash-tags

이렇게 설계하는 것이 더 좋다

 

 

6 )  세부적인 API 설계

 

앞서 봤던 API Endpoint는 API의 대략적인 역할을 소개하는 데에 그친다

예를 들어 회원가입의 경우

API Endpoint : POST /users 와 같이 표현하는데

이는 새로운 사용자의 정보를 생성한다는 것만 나타내고

회원가입을 통해 '무슨 정보를 저장하는가' 를 알려주지 않는다는 것이다

 

그래서 필요한 것이 세부적인 API 설계다

세부적인 API 설계를 위한 키워드

1.  path variable
2.  query string
3.  request body
4.  request header

* 이때 path variable만 API Endpoint에 포함

 

[ 1 ]  path variable

 

게시글 하나 상세 조회 API -> 특정 게시글을 식별할 수 있는 데이터(식별값) 넘기기

GET /users/articles/4

-> 여기서 4가 게시물의 식별값을 의미한다

 

API 명세서에서는 아래와 같이 표현한다

GET /users/articles/{articleId}

 

[ 2 ]  query string

 

검색 조회 -> 특정 조건 만족하는 게시글 검색

* 조건이 하나인 경우

GET /users/articles?name=umc

* 조건이 두개 이상인 경우

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

 

[ 3 ]  request body

request body는 서버로 데이터를 전달해야 하는 상황에서

url에 노출되지 않고 해당 데이터를 json의 형태 혹은 form-data 형태로 포장해서 보낼 수 있도록 한다

 

[ 4 ]  request header

request header는 서버로 데이터를 전달할 때

'전송'에 대한 기타 정보들이 담기는 부분이다

 

 

🔥 미션 - API 명세서 작성 🔥

https://www.notion.so/makeus-challenge/API-657835b6a09942caab7aacbbf1515255?pvs=4

API 명세서

보완 중...

 

2.  Springboot 프로젝트 세팅 인증

 

Spring boot 프로젝트 생성

https://start.spring.io

Spring boot 2.7.17 / Java 21 로 설정

 

Intellij 연결

build.gradle에서 mysql 의존성 주석 처리 후 실행 -> 성공!