💡Rest API를 Clean Code와 연계해서 설명한 부분은 제 "개인의견"입니다. 그리고 이 글보다 출처를 보시는게 더 도움되실거에요.
백엔드를 공부하면 "Restful하게 설계 해야 합니다. "라는 말을 꽤 많이 듣게 됩니다. 많이 들어본 말이고, 분명 멘토님께서 잘 설명해주셨음에도 "그런데 Restful한 API가 뭐였찌?" 라는 질문이 무한루프처럼 생기네요 ㅠ
그래서 블로그에 정리를 좀 해두겠습니다.
1. 용어정리
1.1. 인터페이스
우선 인터페이스가 뭔지에 대해 이해하겠습니다. 인터페이스란 한마디로 "기계와 인간 간의 소통창구"입니다.
예시를 통해 살펴보겠습니다.
1. "컴퓨터 - 사람" 을 이어주는 키보드, 마우스
2. "자판기 - 사람"을 이어주는 자판기의 버튼
3. "컴퓨터 - 사람"을 이어주는 모니터, 스크린
4. "SW - 인간"을 이어주는 Navagtion bar, 버튼, 인풋창 등등
(이 경우는 UI : User Interface)
5. "컴퓨터 - 인간"을 이어주는 윈도우OS, 리눅스
(윈도우 - GUI : Graphic User Interface)
(리눅스 - CLI : Command Line Interface)1.2. API (Application Programming Interface)
인터페이스가 "무엇 - 무엇" 을 이어주는 장치, 서비스, SW라는걸 알게되었습니다. 그럼 API가 무엇일까요? API를 풀어서 이해해보면 "어플리케이션 - 어플리케이션"을 이어주는 인터페이스입니다.
예시를 통해 알아보겠습니다.
1. Velog에서 포스팅을 할 때,
"웹브라우져 - 서버"를 연결해주는
인터페이스가 있을겁니다.
이 인터페이스를 (API) 통해
이 글이 서버의 DB에 저장이 됩니다.
2. 글을 읽을 때도,
DB에 저장된 포스팅을 GET하는 API를 통해
브라우져에서 읽을 수 있게 되는것이죠.이렇게 "어플리케이션 - 어플레케이션"을 이어주는 인터페이스가 API입니다.
2. Rest API
Rest API는 API를 설계 방식 중 하나입니다. 과거에는 SOAP라는 방식을 사용했다고 하는데 굉장히 복잡한 형식이었다고 합니다.
반면에 Rest API는 상대적으로 간결하고 설계하기 쉬운 방식이라고 합니다.
2.1. Rest API의 특징
Rest API의 특징은 각 요청이 어떤 동작이나 정보를 위한 것인지 요청 자체에서 들어나는 것입니다.
좋은 코드 의 특징은 "누가 봐도 이해가 되는 코드" 입니다. Restful한 API의 특징 또한 "누가 봐도 뭘 요청하는지 이해가 되는 API" 라고 보면 되겠습니다.
2.2. Restful하게 설계하는 법
그럼 "Restful한 API를 설계하기 위해선 어떻게 해야하는 걸까요?"
Restful API를 위한 지침에 앞서 클린코드를 위한 지침을 먼저 살펴보겠습니다. Clean Code를 지향하는 분들은 아래와 같은 지침을 가지고 코드를 작성합니다.
1. "유의미한 이름"을 사용하라.
2. "함수는 하나의 역할"만 해야한다.
3. "명령과 조회"를 "분리"하라.
등등...Rest API도 Clean Code 와 유사한 방식으로 설계하면 됩니다. 🚨Restful하지 않은 예시를 먼저 살펴보겠습니다.
1. 학원의 반 리스트 요청 : https://(도메인)/1
2. 반의 학생들 리스트 요청 : https://(도메인)/hello
3. 학생의 정보 수정 요청 : https://(도메인)/hyot-hong
위와 같이 API를 설계해도 구현만 가능하면 서비스가 돌아가는데 문제는 없습니다. 사용자는 도메인뒤에 달린 주소까지 기억하거나 살펴보진 않으니까요. 하지만 👨💻👨💻협업의 관점에선 어떨까요?
만약 저렇게 API를 짠 개발자가 퇴사를 한다면??? 다음 개발자는 API를 파악하기 위해 야근에 시달리지 않을까요?? 😭😭😭😭😭
이번엔 👍Restful한 API의 예시를 보겠습니다.
1. https://(도메인)/classes
2. https://(도메인)/classes/2
3. https://(도메인)/calsses/2/students
4. https://(도메인)/calsses/2/students/15
5. https://(도메인)/calsses/2/students?name=피카츄
6. https://(도메인)/calsses/2/students?page=2&count=10주석을 달지 않아도 대충 무슨 API인지 알것 같지 않나요? 이렇게 URI를 통해 어떤 정보를 요청하는 Get Method인지 명확하게 표현해야 Restful한 API설계 입니다.
또한 HTTP에서의 "GET, POST, DELETE, PUT, PETCH" 메서드를 사용할 때, 각각의 메서드에선 그 메서드에 해당하는 동작만 하도록 만들어야 Restful한 API설계입니다. 위에서 살펴본 Clean Code 지침과 유사하지 않나요? ㅎㅎ
하지만 HTTP 메서드를 URI에 명기하면 URI가 보기 힘들게 복잡해집니다. 따라서 URI는 명사로만 작성해야 Restful한 API가 된다고 합니다.
4. Rest API 설계 원칙
💡 Rest API 설계 원칙의 창시자 Roy Feliding영상
관심있으시면 영상을 한번 보시는걸 추천드립니다.
저는 안봤..
2000년도에 Roy Fielding이 REST 원칙으로 HTTP 요청 API를 설계하면 좋을 것 같다는 논문을 발표합니다.
로이 필딩이 말한 REST 설계 원칙은 다음과 같습니다.
1. Uniform Interface (URL 설계 원칙)
2. Client-Server 역할 구분
3. Stateless (요청간의 의존성 없어야됨)
4. Cacheable
5. Layered System
6. Code on Demand여기서 우리가 집중해야 하는 부분이 {1. Uniform interface}이다.
이는 위에서 말했던 것과 같이
1) URL작성 시 간결, 일관적이어야 함.
2) URL만으로 어떤 요청인지 알 수 있어야함.
등등... 이를 위해
1) URL은 명사로 명명
2) 하위문서를 나타낼 땐 '/' 사용
3) 파일 확장자 쓰지 않기
4) 띄워쓰기는 (-)사용
5) 자료 하나당 하나의 URL5. 정리
정리해보면 Rest API의 목표는 각 요청들을 통해 무엇을 요청하는지 한번에 알 수 있도록 만들어야 하고, 가독성이 좋은 API를 만드는것이 목표라고 할수있겠습니다.
그리고 이런 Restful 한 API를 설계하기 위한 지침은 아래와 같이 정리하면 될것같습니다.
1) URI에 어떤 데이터에 대한 API인지 명시
2) URI는 명사만 기입
3) 각 HTTP 메서드는 해당 메서드에 해당하는 요청만 동작
📝 오늘은 REST API가 뭔지, Restful한 API 설계가 뭔지 알아보면서 포스팅을 해봤습니다. 글을 쓰다보니 출처에 나오는 내용에 더해 나름의 생각을 추가하게 되고, 그러면서 자연스레 머릿속에 정리가 되네요. 그리고... 무언가 설명 글을 쓴다는게 정말 어렵네요. 개발자는 글을 잘 써야 한다던데 개발자의 개발이 자기개발이었나요? 🤣🤣
개념은 어느 정도 알게 되었으니 API설계를 할 수 있게 될까요?! 그건 또 삽질 하며 하나씩 배워나가야겠죠.. ? 이제 과제 (삽질)하러 갑니다.🚀🚀
