[Restful] REST API Design

REST API

 프로젝트에 투입된지 시간이 되어 개발자에 조금 익숙해진 듯 하지만 사실은 아니라는 것을 절실히 느끼면서 아래 내용을 남겨본다 ㅋㅋ!

 프로젝트의 아키텍쳐가 트렌드에 맞춰 서버와 클라이언트를 분리시키고, 클라이언트에 데이터를 전달하는 방식으로 Restful 아키텍쳐를 선택하였으며, 아쉽게도 클라이언트 프레임워크는 없었다(이는 프로젝트의 대 참사를 불러온다ㅋㅋㅋ). 아직은 신입개발자라 아키텍쳐에 대해서 1도 모르지만 공부하여 정리해보았다.

0. REST API? RESTFUL?

 사람들이 흔이 헷갈려하는 것이 RESTFUL이 아키텍쳐 디자인인줄 인식한다는 것이다. 정확히는 "REST 구조 스타일로 API가 이루어진 서비스를 RESTFUL하다!"라고 한다. 

1. REST API 디자인 기본 규칙

 REST API는 Resource를 나타낼 때 URI를 사용하는데 이 URI를 설계하는데 몇가지 규칙이 있다.

 

 1) RFC 3986에 따라 URL는 우측과 같은 구조로 설계된다. URI = scheme “ :// ” authority “ / ” path [“ ? ” query] [“ # ” fragment ]

 2) 슬래시 구분자(/)는 계층 관계를 나타내는데 사용한다.
    http://api.studentmanagement.com/grades/3/classes/11/students

 3) 마지막엔 슬래시 구분자(/)를 포함하지 않는다.

    잘못된 예 : http://api.studentmanagement.com/grades/3/classes/11/students/

 4) 하이픈(-)은 URI 가독성을 높이는데 사용한다. 

    솔직히 이에 대해서는 동의가 안된다, 물론 가독성 자체가 높아지긴하지만 resource name이 만약 KimSeougSu 같은 카멜표기로 될 수도 있기 때
    문이다...

 5) 밑줄(_)은 사용하짐 말자

 6) URI는 소문자로! 왜냐하면 호스트(www.naver.com같은)는 대소문자를 구분하지 않지만 URI 호스트와 스키마를 제외한 곳은 대소문자를 구분한

    다

 7) 파일확장자는 URI에 포함하지 않는다.

2. 리소스 원형

 리소스 원형을 REST API에 URI를 디자인할 때 쓰는 모든 Resource들을 지칭하는 말인데, 도큐먼트, 컬렉션, 스토어, 컨트롤러로 구성된다.

 도큐먼트 : 데이터베이스의 row단위 또는 리스트 컬렉션의 하나의 객체단위로 단일 정보를 포함하고 있는 데이터라고 생각하면 쉽다.

 컬렉션   : 도큐먼트들의 집합이다. 관리 주체는 서버이며 컬렉션은 클라이언트에서 새로운 리소스를 제안해서 올릴 수 있으나 결정은 서버가 한다.

 스토어   : 컬렉션과 같이 도큐먼트들의 집합이며 관리 주체는 클라이언트이다. 클라이언트는 기존의 리소스를 스토어 추가하거나 삭제 변경할 수

             있지만 새로운 리소스를 생성할 수 없다.

 컨트롤러 : 컬렉션, 스토어의 메서드의 기능이라고 생각하면된다. HttpMethod(CRUD)를 제외한 특정한 기능을 요구할 때 사용된다.

 http://api.studentmanagement.com/grades/3/notice?title=하계수련회&content=하계수련회 관련 공지입니다.

 위 예제를 가지고 알기 쉽게 설명하자면 grades라는 컬렉션에 3(학년)이라는 도큐먼트가 존재하며 notice라는 컨트롤러를 통해 하계수련회(내용 : 하계수련회 공지입니다.)라는 내용을 공지했다~ 라는 의미이다. 3초만에 정말 기능에 대해서 파악이 가능한게 REST API의 장점이다!

3. 명명규칙

 리소스원형들을 URI에 표현하기 위해서 아래와 같은 규칙을 따른다.

 

 1) 도큐먼트는 단수 명사이여야한다. (1, 2, 3, team1, team2, kim-sungsu, lee-hana etc..)

 2) 컬렉션과 스토어는 복수 명사여야한다. (names, titles, teams, projects etc...)

 3) 컨트롤러는 동사나 동사구야한다. (isExist, dedupe, reindex, register)

4. Http Method

 특정한 도큐먼트를 수정하거나 컬렉션에 새로운 리소스 생성에 대한 제안을 할 때 사용한다.

 1) GET : 말그대로 겟!! 정보를 가져온다. 목록이든 상세이든 상관없다!

 2) POST : 생성

 3) PUT(PATCH) : 수정

 4) DELETE : 삭제

 GET http://api.studentmanagement.com/grades/1/classes/3/students

 : 1학년 3반의 학생 목록을 조회한다.

 GET http://api.studentmanagement.com/grades/1/classes/3/students/21

 : 1학년 3반의 21번 학생 정보를 조회한다.

 POST http://api.studentmanagement.com/grades/1/classes/3/students

 : 1학년 3반의 새로운 학생을 추가한다. (서비스에 따라서 도큐먼트 명을 직접 지정할 수도 서버에서 인덱싱을 새로운 유니크 키를 할당할 수 도있다

  물론 학생에 정보는 request 패킷의 body에 존재한다.

 PUT http://api.studentmanagement.com/grades/1/classes/3/students/11

 : 1학년 3반 11번 학생의 정보를 수정한다.

 DELETE http://api.studentmanagement.com/grades/1/classes/3/students/11

 : 1학년 3반 11번 학생의 정보를 제거한다.

5. 유의할 점

 REST API를 설계하다보면 실수 아닌 실수가 나오곤 하는데 별거 아니다라는 생각을 가지지말고 꼭 지켜야한다.

 1) URI에서 변할 수 있는 부분(도큐먼트에 대한 지정자)는 무조건 유니크한 값이여야 만한다. 3학년 1번에 33번호를 가진 학생은 2명이 될 수 없다.

 2) 컨트롤러를 남용하지마라. method를 이용해 충분히 처리가 가능함에도 파라미터나 컨트롤러를 사용하지 말자

    예1 : http://api.studentmanagement.com/grades/1/classes/3/students/11/delete

    예2 : http://api.studentmanagement.com/grades/1/classes/3/students/11?requestType=delete

 

6. 비고

 OPEN하지 않는 서버간의 통신에도 굳이 REST API를 사용할 필요는 없으며 오히려 JSON 방식의 REST API를 사용함으로서 서버간의 통신이 느린 경우도 있다. 차라리 서버간의 통신이고 외부에 공개할 필요가 없고 앞으로도 그러지 않은 것이라는 통신이면 WEB API로 header 값에 다양한 필터조건을 넣어주는게 더 깔끔할 수 있다.