업무중에 URI 네이밍(설계)을 할 기회가 생겼는데 URI의 계층적 구조에 대한 이해가 부족하여 올바르지 못한 URI를 작성하고 피드백을 받아 이를 정리하기 위한 포스트 입니다.
🍑 URI (Uniform Resource Identifiers)
REST API는 주소자원으로 URI를 사용함.
URI 디자인은 API의 리소스 모델을 명확하게 전달하는 방식으로 작성 해야한다.
REST API 설계자는 REST API가 반환하는 자원을 잠재적 클라이언트 개발자에게 전달할 URI를 디자인 규칙을 통해 만들어내야함.
🍊 URI 규칙 소개
아래와같은 일반 URI 구문을 이용해 설명 합니다.
URI = scheme "://" authority "/" path [ "?" query ][ "#" fragment ]
❄️ 규칙 1 : 후행 슬래쉬(/)는 URI에 포함되지 않아야 합니다.
후행 슬래쉬는 의미가 전혀 없을 뿐아니라 혼란을 야기할 수 있기 때문이다.
그 예로 많은 웹 컴포넌트나 프레임워크들은 다음의 두 URI를 동일하게 다룬다.
EX) http://jason.co.kr/needmore
EX) http://jason.co.kr/needmore/
그러나 URI에 있는 모든 문자들은 리소스의 고유한 ID로 계산되기 때문에 두개의 다른 URI는 다른 2개의 리소스로 매핑됨.
URI가 다르다면 리소스도 달라지게 되고, 그래서 REST API는 명확한 URI를 생성해야한다.
또한 클라이언트가 부정확하게 접근하려는 시도들을 모두 고려하여 작성해야한다.
우리의 개발 파트너들만이 API 호출 대상이 아니기 때문!!
❄️ 규칙 2 : 계층관계를 나타낼 때 슬래시 구분자를 사용해야합니다.
슬래시문자는 URI의 경로 부분에서 자원 간의 계층적 관계를 나타내기 위해서 사용한다.
EX) http://board.com/boards/52 -> 게시판의 52번글.
❄️ 규칙 3 : URI의 가독성을 높이기 위해서 하이픈(-) 문자를 사용합니다.
당신이 정의한 URI가 사람들에게 더 쉽게 읽힐 수 있게 하기 위해서 긴 Path를 표현하는 단어는 하이픈으로 구분해두는 것이 좋음.
EX) http://api.example.com/blogs/miot-jason/posts/this-is-my-post
❄️ 규칙 4 : 언더바( _ ) 문자는 URI에 사용하지 않습니다.
텍스트 뷰어 프로그램은(예를 들어, 브라우저, 에디터 등) 클릭할 수 있다는 것을 표현하기 위해 URI에 밑줄을 그어 놓는 경우가 있음.
프로그램의 글자 폰트에 따라서 언더바 문자( _ )는 이러한 밑줄처리에 의해 문자가 부분적으로 가려지거나 완전히 숨겨질 수 있다..!!
이러한 혼란을 피하기위해 언더바 문자보다는 하이픈 문자를 사용하는게 좋다.
❄️ 규칙 5 : URI를 작성하는 데에는 소문자가 적합하다.
대문자는 때로 문제를 일으키는 경우가 있기 때문!
❄️ 규칙 6 : 파일확장자는 URI에 포함하지 않습니다.
웹상에서 점( . )은 파일명과 확장자를 구분짓는 데에 사용되는 문자이지만,
REST API는 메시지 엔티티 바디의 본문 형식을 표시하기 위해 이러한 파일 확장자를 URI에 포함하면 안된다.
대신에 Content-Type이라는 헤더를 통해 전달되는대로 미디어 타입을 사용하여 body의 콘텐츠를 처리하는 방법을 결정.
❄️ 규칙 7 : 보통 URI는 영어로 작성되는데 작성되는 영어를 단수형으로 작성해야하는가 복수형으로 작성해야 하는가?
단순유지(keep-it-simple) 규칙이 여기에 적용됩니다.
하나의 인스턴스를 복수형으로 표시하는게 영어문법적으로 맞지 않겠다고 생각할 수도 있지만 URI의 형식을 복수형으로 사용하는 것이 실무에서 많이 사용되고 있음.
이상한 복수형(person/people과 같은)을 다루지 않아도 API 소비자가 편하게 이용하고 API 제공업체가 구현하기가 쉬워집니다.
(대부분의 최신 프레임워크가 /students(복수형) 및 /students/232324(복수형 중 특정하기) 형태로 처리됨)
EX) http://api.college.com/students/3248234/courses
ID가 3248234인 학생이 학습한 모든 과정 목록 검색
http://api.college.com/students/3248234/courses/physics
ID가 3248234인 학생을 위한 과정중 물리학을 검색한다.
🍋 결론
REST API 서비스를 디자인할 때, URL을 디자인할 resource에(students와 같은) 주의를 많이 기울여야 한다.
서비스의 모든 리소스들은 최소 하나의 URI로 구분하는게 좋음.
EX)api.test.com/users
모든 유저 검색
api.test.com/users/12345/name
ID:12345 유저의 이름 검색
EX) api.test.com/files/12345/name
특정 URI가 리소스를 적절히 설명할 수 있을 때 가장 좋은 디자인이라고 볼 수 있다.
URI는 이해력을 높이기 위해서 예측 가능해야하고, 계층 구조적이어야 한다.
즉, 일관성이 있다는 관점에서 예측가능하고, 데이터가 구조를 갖추고 있다는 점에서 계층적이다는 것입니다.
RESTFul API는 소비자이며,
URI의 이름이나 구조는 이러한 소비자에게 의미를 전달할 수 있어야 한다.
위의 규칙들을 적용한다면 더욱 명확한 REST API를 구축해볼 수 있을 것이고 API를 호출하는 개발자는 편하게 작성된 API를 사용할 수 있을 것 입니다.
반드시 지켜야하는 제약같은 것은 아니지만, 여러분이 위의 규칙들을 준수해봄으로써 API는 깨끗해질 수 있을 것입니다.
