RESTful API 설계 규칙

2019. 7. 26. 16:56ㆍ개발 & 전산/Web & Network

프로젝트를 하면서 API를 설계할때 늘상 헷갈리는 것이 Rest API입니다. 한번 정리해두고 늘 참고합시다.

Representational State Transfer (REST) refers to a group of software architecture design constraints that bring about efficient, reliable, and scalable distributed systems.
- MDN의 REST

REST란 Representational State Transfer의 약자로, MDN에 따르면 효과적이고 신뢰를 주고 측정가능한 분산시스템을 위한 소프트웨어 설계 제약 사항입니다. 즉, 자원을 정의하고 그 주소를 지정하는 전반의 방법을 말하는 것입니다.

REST의 기본 개념은 상태와 관계가 잘 정의되고 표준화한 포맷으로 document같은 리소스를 전송하는 것입니다. 이 방식을 잘 적용한 설계를 RESTful 이라고 합니다.

 

1. REST API 기본규칙

  1. URI는 정보의 자원을 표현해야 한다.

    1. resource는 동사보다는 명사를, 대문자보다는 소문자를 사용한다.
    2. resource의 스토어 이름으로는 복수 명사를 사용해야 한다.

  2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)으로 표현한다.

    1. HTTP Method나 동사표현이 URI에 들어가면 안됩니다.
    2. :id와 같이 변하는 값은 하나의 특정 resource를 나타내는 고유값이어야 합니다.

흔히 하는 실수는 URI에 자원에 대한 행위를 넣는 것입니다.

// 잘못된 사례
GET /chatrooms/get/:id
POST /chatrooms/create
GET /chatrooms/delete/:id
POST /chatrooms/update/:id

위 잘못된 사례는 아래와 같이 고칠 수 있습니다.

// 올바른 사례
GET /chatrooms/:id
POST /chatrooms
DELETE /chatrooms/:id
PUT /chatrooms/:id

 

  1. HTTP Method
  • 주로 쓰는 Method
    • GET: 조회 (받겠다)
    • POST: 리소스 생성 (보내겠다)
    • PUT: 리소스 전체 갱신(놓겠다/넣겠다)
    • PATCH: 리소스 부분 갱신(붙이겠다)
    • DELETE: 리소스 삭제 (지정한 서버의 파일을 삭제하겠다)
  • 나머지 Method
    • HEAD: GET과 유사하나 HTTP 메시지 헤더만 반송하고 데이터 내용을 돌려보내지 않음(헤더만 보겠다)
    • OPTION: 통신 옵션을 통지/조사
    • TRACE: 리퀘스트 라인과 헤더를 그대로 클라이언트에 반송(리퀘스트 치환상태를 조사할 때 사용)
    • CONNECT: 암호화된 메시지를 프록시로 전송
  1. 설계 예시
         

    CRUD

    HTTP

    URI

    전체 리소스 조회

    GET

    /resources

    특정 리소스 조회

    GET

    /resources/:id

    리소스 생성

    POST

    /resources

    리소스 전체 수정

    PUT

    /resources/:id

    리소스 일부 수정

    PATCH

    /resources/:id

    특정 리소스 삭제

    DELETE

    /resources/:id

2. Rest API 세부규칙

  1. 슬래시(/)는 계층 관계를 나타냅니다.
http://www.example.com/fruits/banana

 

  1. URI의 마지막엔 슬래시(/)를 포함하지 않습니다.
http://www.example.com/fruits/banana/ (X)

 

  1. 가독성을 높이기 위해 하이픈(-)을 사용할 수 있으나 언더바(_)를 사용하진 않는다.
http://www.example.com/tropical_fruits/banana/ (X)
http://www.example.com/tropical-fruits/banana/ (O)

 

  1. URI 경로에는 소문자를 씁니다.
http://api.example.restapi.org/my-folder/my-doc
HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc

위의 두 URI는 같은 URI입니다. 호스트에서는 대소문자를 구별하지 않기 때문이지요.

http://api.example.restapi.org/my-folder/my-doc
http://api.example.restapi.org/My-Folder/my-doc

하지만 위의 두 URI는 다른 URI입니다. 뒤에 붙는 path가 대소문자로 구분되기 때문입니다.

RFC 3986에 따르면 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정한다고 합니다. 따라서 전부 소문자이거나 전부 대문자이면 괜찮지만, 일반적으로 대문자는 잘 쓰지 않기 때문에 소문자로 쓰는 것을 권합니다.

예시출처: RESTful API를 설계하기 위한 디자인 팁(https://spoqa.github.io/2013/06/11/more-restful-interface.html)

 

  1. 파일 확장자는 URI에 포함하지 않고 Accept header을 사용합니다
  2. 리소스간 연관관계가 있는 경우

  • /리소스명/리소스ID/관계있는 다른 리소스명(일반적으로 소유has의 관계)

    GET /users/:id/skills

 

참고문헌

 

티스토리툴바