[Spring 5] REST API, RESTful API 이름 짓기

1. API와 REST API

API(Applicaation Programming Interface)는 서로 다른 소프트웨어 프로그램끼리 서로 소통하고 데이터를 주고받기 위해 설정한 규약, 약속이다. API를 활용하면 사용자는 내부 로직을 볼 수 없고 결과만 볼 수 있기 때문에 보안적으로도 안전하고 결과값만 조회 할 수 있어 효율적이다. 또한 java든 python이든 다른 언어나 환경에 관계없이 다양한 시스템을 연결할 수 있다는 장점이 있다.

 

REST API(Represetational State Transfer API)는 웹에서 데이터를 주고 받기 위한 아키텍쳐 스타일이다. 특정 기술을 말하는 단어가 아니고, 데이터를 어떻게 바라보고 어떤 주소로 보낼지를 지정하는 방법론에 가깝다고 할 수 있다. REST API에서는 모든 것을 자원(Resource)로 간주한다. 여기서 자원은 우리가 제공하는 기능을 말한다. 그리고 각 resource를 HTTP URI(Uniform Resource Identifier)로 고유하게 표현한다. 그리고 해당 resource에 대한 행위는 GET(조회), POST(생성), PUT(수정), DELETE(삭제)와 같은 HTTP Method로 정의한다.

• 자원 (Resource): 서버가 관리하는 데이터 (예: 사용자, 게시글, 이미지)
• 행위 (Verb): HTTP 메서드를 통해 자원에 대한 조작을 정의 (GET, POST, PUT, DELETE)
• 표현 (Representation): 자원이 실제 전달되는 형태 (주로 JSON, XML)

REST 설계 원칙을 잘 준수한 시스템을 RESTful 하다고 말한다. 실무적으로는 보통 3가지를 만족하는지를 주로 확인한다.

첫번째는 resource를 동사가 아닌 명사로 표현할 것.

두번째는 URI에는 행위를 동사로 표현하지 않고 HTTP Method로 구분하는 것.

세번째는 JSON, XML 등 데이터 형식을 명시해서 클라이언트가 자원을 어떻게 처리하는지 알게 할 것.

이렇게 3가지가 중요하게 체크해봐야한다. 즉, 우리가 설계할 때는 RESTful하게 API Naming을 하는 것이 중요하다.

 

 

REST API에서 사용하는 HTTP 프로토콜에 대해서는 컴퓨터네트워크 과목을 배울 때 정리해둔 내용이 있다. HTTP와 HTTP Method에 대해 헷갈린다면 아래 페이지에서 내용을 다시 짚고 API Naming으로 넘어가자.

 

[HTTP 프로토콜이란?]

[네트워크] 15. HTTP, DNS, FTP, TFTP, 네트워크보안

---

2. API Naming

가장 API Naming에서 가장 신경써야할 것은 위에서 말한 세가지이다.

 

첫번째는 resource를 동사가 아닌 명사로 표현할 것. 

두번째는 URI에는 행위를 동사로 표현하지 않고 HTTP Method로 구분하는 것. 

세번째는 JSON, XML 등 데이터 형식을 명시해서 클라이언트가 자원을 어떻게 처리하는지 알게 할 것.

 

URI가 아닌 HTTP Method로 행위를 구분한다는 것은 URI에는 명사를 쓰고 POST, GET, PUT, DELETE로 행위를 구분하겠다는 말이다.

/articles         // 목록을 위한 URL
/articles/1234    // 목록 중 특정 개체를 위한 URL

위와 같은 URI가 있을 때 HTTP Method에 따라 아래와 같이 의미가 달라지게 되는 것이다.

Resource	POST (생성)	GET (조회)	PUT (수정)	DELETE (삭제)
`/articles`	새로운 article 생성	article 목록 보기	articles에 대한 대량 업데이트	모든 articles 삭제
`/articles/1234`	에러	특정 article 보기	있으면 업데이트, 없으면 에러	삭제

 

이 외에도 API Naming에서 지켜야할 여러가지 규칙들이 있다. 하나씩 살펴보자.

 

1. resource는 명사를 사용하며, 복수명사 사용을 권장한다. URI는 행위(동사)가 아닌 리소스(명사)을 나타내야한다.

    좋은 예시: /users, /users/1    잘못된 예시: /getUsers, /create_user, /user/1

 

2. 계층 관계는 슬래시(/)로 구분한다. 자원 간의 포함 관계나 종속 관계를 나타낼 때 계층 구조를 사용해서 depth로 표현한다.

    좋은 예시: /users/1/orders (1번 사용자의 주문 목록)

 

3. 밑줄(_) 대신 하이픈(-)을 사용해야한다. URI의 가독성을 높이기 위해 단어 구분자로 하이픈(Kebab-case)을 사용하는 것이 관례인데 밑줄은 글꼴에 따라 링크 밑줄과 겹쳐 보이지 않을 수 있기 때문이다.

    좋은 예시: /user-profiles    잘못된 예시: /user_profiles

 

4. 소문자만 사용한다. RFC 3986(URI 문법 표준)에 따라 URI 경로 부분은 대소문자를 구분할 수 있지만, 혼란을 방지하기 위해 모두 소문자로 작성하는 것이 원칙이다.

    좋은 예시: /users/v1/login    잘못된 예시: /Users/v1/Login

 

5. 파일 확장자는 URI에 포함하지 않는다. 데이터의 형식(JSON, XML 등)은 URI에 직접 쓰지 않고, HTTP 헤더의 Accept 필드에서 명시한다.

    좋은 예시: /users/1/profile-photo (Header에 Accept: image/jpeg 지정)    잘못된 예시:  /users/1/profile-photo.jpg