Express로 서버 구성하기 RESTful api - 7

Posted by Kyun2da on January 2, 2021

1️⃣ 서론

안녕하세요. 본격적으로 rest방식으로 라우팅을 하기 전에 한가지 개념을 먼저 짚고 넘어 가보고자 합니다.

바로 RESTful api인데요.

이번 시간엔 REST api 의 튜토리얼을 정리해보면서 포스팅을 해보려고 합니다.

그럼 시작하겠습니다!

2️⃣ REST 란?

RESTful api에서 REST의 뜻은 무엇일까요?

이 용어는 로이 필딩(Roy Fielding)의 2000년 박사학위 논문에서 소개되었습니다.

REST는 (Representational State Transfer) 의 약자로써 웹과 같은 하이퍼미디어 시스템을 위한

소프트웨어 아키텍쳐의 한 형식입니다.

좀더 자세한 의미로는 자원을 정의하고 자원에 대한 주소를 지정하는 방법들의 모음이라고 합니다.

이러한 Rest 원리를 따르는 시스템을 종종 Restful 이라고 한답니다.

3️⃣ REST의 원칙

REST의 원칙에는 6가지가 존재합니다.

  1. Client-server : 데이터 저장으로 부터 사용자 인터페이스를 분리함으로써, 사용자 인터페이스의 이식성을 개선하고 서버 구성요소를 단순화하여 확장성을 개선합니다.

  2. Stateless : 클라이언트와 서버간 각 요청은 요청을 이해하는데 필요한 모든 정보를 포함해야 하며, 서버는 저장된 컨텍스트를 이용할 수 없습니다. 따라서 세션 상태는 전적으로 클라이언트에 의해 유지됩니다.

  3. Cacheable : 캐시 제약 조건을 사용하려면 요청에 대한 응답 내의 데이터를 암시적으로 또는 명시적으로 캐시 가능 or 캐시 불가능이라고 명명해야합니다. 응답을 캐싱할수 있는 경우, 클라이언트 캐시에는 동등한 요청을 위해 해당 응답 데이터를 재사용할 수 있는 권한이 부여됩니다.

  4. Uniform interface : 일반적인 소프트웨어 공학 원리를 요소 인터페이스에 적용함으로써, 전체적인 시스템 아키텍쳐를 단순화하고 상호작용을 개선합니다. 통일된 인터페이스를 얻기 위해서는 요소들의 동작을 유도하기 위해 복수의 구조적 제약조건이 필요합니다. REST는 인터페이스 제약, 즉 자원의 식별, 표현을 통한 자원의 조작, 자기 설명 메시지, 애플리케이션 상태의 엔진으로서의 하이퍼미디어로 정의됩니다.

  5. Layered system : 계층화된 시스템 스타일은 각 요소들이 상호작용하고 있는 직접적인 계층을 넘어서서 “보일” 수 없는 요소 행동을 제한함으로써 아키텍처가 계층으로 구성될 수 있도록 합니다.

  6. Code on demand : REST를 사용하면 애플릿 또는 스크립트 형식으로 코드를 다운로드하고 실행하여 클라이언트 기능을 확장할 수 있습니다. 이를 통해 사전 구현에 필요한 기능 수를 줄임으로써 클라이언트를 단순화할 수 있습니다.

4️⃣ REST와 HTTP는 다르다!!

REST는 웹(인터넷)을 보다 합리적이고 표준적으로 만들기 위해 REST 원칙을 더욱 엄격하게 사용할 것을 주장합니다. 여기서부터 사람들은 REST를 웹(HTTP)과 비교하기 시작합니다. Royfielding은 자신의 논문에서 프로토콜 선호도와 HTTP를 포함한 구현 지침을 전혀 언급하지 않았습니다. REST의 6가지 지침 원칙을 준수하기만 한다면 인터페이스를 RESTful이라고 부를 수 있습니다.

간단히 말해, REST 아키텍처 스타일에서 데이터와 기능은 리소스로 간주되고 URI(Uniform Resource Identifier)를 사용하여 액세스합니다. 리소스는 일련의 단순하고 잘 정의된 작업을 사용하여 수행됩니다. 클라이언트와 서버는 표준화된 인터페이스 및 프로토콜(일반적으로 HTTP)을 사용하여 리소스 표현을 교환합니다.

리소스는 표현에서 분리되므로 HTML, XML, 일반 텍스트, PDF, JPEG, JSON 등과 같은 다양한 형식으로 컨텐츠에 액세스할 수 있습니다. 리소스에 대한 메타데이터를 사용할 수 있으며 이를 통해 캐싱을 제어하고, 전송 오류를 감지하고, 적절한 표현 형식을 협상하고, 인증 또는 액세스 제어를 수행할 수 있습니다. 가장 중요한 것은 리소스와의 모든 상호 작용이 상태 비저장(stateless)이라는 것입니다.

이러한 모든 원칙은 RESTful 애플리케이션을 단순하고 가볍고 빠르게 만드는 데 도움이 됩니다.

5️⃣ REST 명명 규칙

명명 규칙은 크게 4가지로 볼 수 있습니다.

1. 자원을 표현하는데에 명사를 사용하자

RESTful URL은 동사로 표현하기 보다는 명사로 표현해야 합니다. 명사는 동사가 가지고 있지않는 속성을 갖고있기 때문입니다. 다음과 같은 예제들이 있습니다.

  • 시스템의 유저
  • 유저 아이디
  • 네트워크 Device 들
    그리고 아래와 같이 쓰일 수 있습니다.
1
2
3
4
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/
http://api.example.com/user-management/users/{id}

좀더 명확하게 하기 위해서 자원을 네가지 범주(document, collection, store, controller)로 나눈 다음, 항상 하나의 원형을 목표로 잡아두고 다음 자원의 명명 규칙을 일관되게 사용해야 합니다.

이제 그 4가지의 명명 규칙을 하나하나 자세하게 알아보도록 하겠습니다.

  1. document
    document 리소스는 개체 인스턴스 또는 데이터베이스 레코드와 유사한 단일 개념입니다.

    일반적으로 문서의 상태표시에는 값이 있는 필드와 다른 리소스에 대한 링크가 모두 포함됩니다.

    문서 리소스의 원형을 나타내려면 아래와 같은 예처럼 단일 이름을 사용해야 합니다.

    1
    2
    3
    
    http://api.example.com/device-management/managed-devices/{device-id}
    http://api.example.com/user-management/users/{id}
    http://api.example.com/user-management/users/admin
    
  2. collection
    collection 리소스는 서버가 관리하는 리소스 디렉토리 입니다. 클라이언트는 컬렉션에 추가할 새 리소스를 제안할 수 있습니다. 그러나 새 리소스를 생성할지 여부를 선택하는 것은 컬렉션에 따라 다릅니다.수집 리소스는 포함할 항목을 선택하고 포함된 각 리소스의 URI도 결정합니다.

    컬렉션 리소스 원형을 나타내려면 아래와 같은 예처럼 복수 이름을 사용해야 합니다.

    1
    2
    3
    
    http://api.example.com/device-management/managed-devices
    http://api.example.com/user-management/users
    http://api.example.com/user-management/users/{id}/accounts
    
  3. store 스토어는 클라이언트 관리 리소스 저장소입니다.

    저장소 리소스를 사용하면 API 클라이언트가 리소스를 넣고 다시 꺼낸 다음 삭제 시기를 결정할 수 있습니다.

    스토어는 새 URI를 생성하지 않습니다. 대신 저장된 각 리소스에는 URI가 있습니다.

    URI는 처음에 스토어에 넣을 때 클라이언트가 선택했습니다.

    저장소 리소스 원형을 나타내려면 아래와 같은 예처럼 복수 이름을 사용해야 합니다.

    1
    
    http://api.example.com/song-management/users/{id}/playlists
    
  4. controller
    컨트롤러 리소스는 절차 개념을 모델링합니다.

    컨트롤러 리소스는 매개 변수 및 반환 값, 입력 및 출력을 포함하는 실행 가능한 기능과 같습니다.

    컨트롤러의 원형을 나타내려면 아래와 같은 예처럼 동사 이름을 사용해야 합니다.

    1
    2
    
    http://api.example.com/cart-management/users/{id}/cart/checkout
    http://api.example.com/song-management/users/{id}/playlist/play
    

2. 지속성이 핵심입니다

일관성 있는 리소스 명명 규칙과 URI 형식을 사용하여 모호성을 최소화하고 가독성과 유지보수를 극대화할 수 있습니다.

일관성을 유지하기 위해 아래 설계 6가지를 참조해봅시다.

  1. 슬래시(/)를 사용하여 계층 관계를 나타냅니다.
  2. URI 맨 마지막에 (/)를 사용하지 않는것이 좋습니다.
  3. 하이픈(-)을 사용하여 URI의 가독성을 개선합니다.
  4. 밑줄( _)을 사용하지 않는것이 좋습니다.
  5. URI에는 소문자를 사용합니다.
  6. 파일 확장명을 사용하지 않는것이 좋습니다.

3. URI에 CRUD 함수 이름을 사용하지 않는것이 좋습니다

URI를 사용하여 CRUD 기능이 수행되었음을 표시해서는 안 됩니다.

URI는 리소스를 고유하게 식별하기 위해 사용해야 하며 리소스에 대한 작업이 없어야 합니다.

어떤 CRUD 기능이 수행되는지 나타내기 위해 HTTP 요청 방법을 사용해야 합니다. (GET, POST, PUT, DELETE)

4. 쿼리 구성 요소를 사용하여 URI 컬렉션을 필터링합니다

특정 리소스 속성에 따라 정렬, 필터링 또는 제한된 리소스 컬렉션이 필요한 경우가 많습니다.

이를 위해 새 API를 생성하지 말고 리소스 수집 API에서 정렬, 필터링 및 페이지 지정 기능을 활성화하고 입력 매개 변수를 쿼리 매개 변수로 전달합니다.

6️⃣ 마치며..

오늘은 REST에 대해 알아보았습니다.

다음 시간에는 REST를 활용해 EXPRESS로 Restful API를 만들어 클라이언트에 요청한 후 응답을 주는 것 까지 한번 구현해 보도록 하겠습니다.

읽어주셔서 감사합니다.