[chap 6] API URL의 설계 & 프로젝트 세팅

API 설계 시 필요한 것은 아래와 같습니다.

1. API End point의 설계
2. 요청 데이터, 응답 데이터의 설계

그리고 위의 정보를 문서화해서 프론트 개발자가 API를 사용하기 쉽도록 돕는 문서를 API 명세서라고 부릅니다.

Api는 Application을 Programming 할 때 사용되는 인터페이스를 말합니다.

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

 

REST API

REST는 Representational State Transfer의 약자로,

HTTP를 기반으로 하는 웹 서비스 아키텍처를 의미하며 HTTP 메소드와 자원을 이용해 서로 간의 통신을 주고받는 방법입니다.

 

HTTP 메소드

HTTP 메소드는 REST 방식으로 통신 할 때 필요한 작업을 표시하는 방법으로 대표적인  5가지만 말하겠습니다.

그리고 아래의 5개 메소드는 CRUD(생성, 조회, 갱신, 삭제) 4가지에 대응이 됩니다.

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

위의 5개 메소드 중 POST는 새로운 자원의 생성도 있지만, 클라이언트가 특정 정보를 서버로 넘기고 그에 대한 처리를 요청 하는 것을 전부 POST로 처리 가능합니다.

 

RESTful API Endpoint의 설계

이제 RESTful한 API의 설계를 위한 규칙을 알아봅시다.

RESTful한 API의 Endpoint는 아래의 규칙에 따라 설계가 가능합니다.

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

 

세부적인 API 설계

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

위의 4개 중 API endpoint에 포함이 되는 것은 path variable 하나 뿐입니다.

 

Path Variable

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

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

따라서 실제로는 아래와 같겠죠.

GET https://umc.com/users/articles/4 ← 저 4에 주목!

여기서 저 4가 데이터베이스 상에서 게시글의 기본키라는 것을 캐치 한다면 잘 이해한 것입니다.

따라서 /users/articles/id에서 id는 진짜 문자 그대로 id가 아니라 게시글의 식별 값을 의미하죠.

 

실제 Api 명세서에서는 GET /users/articles/{article-id} 이렇게 표현합니다.

 

Query String

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

이런 경우, 1개가 될 수도 있고 여러 개가 될 수도 있잖아요?

따라서 단 하나만 조회하는 path variable을 사용하는 것은 아니고, query string을 활용하는 것입니다.

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

GET /users/articles?name=umc 이렇게 사용할 수 도 있고,

전달할 정보가 여러 개 일 경우, GET /users/articles?name=umc&owner=ddol  이렇게 사용할 수도 있습니다.