번역글 The Fundamentals of REST API Design

이 글은 계정 관리 API 서비스, Auth 서비스를 제공하는 Stormpath의 블로그 글인, The Fundamentals of REST API Design 문서를 번역한 글입니다.
원문은 여기 에서 확인 가능합니다.

Stormpath에서는 개발자들이 REST API 및 언어 별 SDK를 통해 인증, 권한 부여 및 비밀번호 재설정을 포함한 사용자 관리 기능에 쉽게 액세스 할 수 있게 돕고 있습니다. 이 서비스를 구축할 때 Stormpath 내부 팀은 REST + JSON API 디자인에 대한 기존의 보편적인 정보들을 바탕으로 시작했습니다. 이번에 REST API를 구축하는 과정에서 그들은 더 많은 것을 배웠습니다. 그리고 이 경험을 바탕으로 우리의 CTO 인 Les Hazelwood는 REST + JSON API 디자인 모범 사례에 대해 Java 개발자 그룹에게 프리젠테이션을 진행했습니다. 이 사례는 여기서 볼 수 있습니다.

위 프리젠테이션 외에도 REST API와 관련하여 REST API의 보안 REST API의 링크 및 리소스 확장 에 대한 게시물을 작성했습니다.
이 글에서는 Les가 그의 이야기에서 다루는 주요 요점, 특히 우수한 REST + JSON API 디자인의 기본 사항에 대한 높은 수준의 요약을 제공합니다.

왜 REST가 필요한가요?

API의 빠른 결정이라는 목표를 염두에두고 RESTful API가 매력적인 이유는 무엇일까요? REST 패러다임에 관한 Dr. Roy Fielding의 논문에 따르면, REST에는 6가지 뚜렷한 이점이 있습니다.

  1. 확장성 - 반드시 성능이 보장되는 것은 아니지만, RESTful API가 다른 시스템에 적응하고 확장하여 연결되는 것은 정말 간단하고, 쉽습니다.
  2. HTTP 사용 - HTTP 메소드를 사용하여 자원을 관리하면 RESTful API를 외부의 다른 응용 프로그램에서도 쉽게 연결하고 사용할 수 있습니다.
  3. 독립성 - REST API를 사용하면 전체 애플리케이션 또는 전체 웹 서버를 종료하지 않고도 애플리케이션의 특정 부분을 재배치하거나 축소 할 수 있습니다.
  4. Caching으로 인한 대기 시간 감소 - REST API는 Caching의 우선 순위를 지정 및 활용 가능하기 때문에 대기 시간이 향상됩니다. 따라서 REST API를 개발할 때는 항상 캐싱을 최우선으로 생각해야 합니다.
  5. 보안 - HTTP 통신을 사용하면 특정 HTTP 헤더를 통해 보안을 파악할 수 있으므로 이를 활용하여 API를 안전하게 할 수 있습니다.
  6. Encapsulation - REST를 사용하면 숨김이 필요한 일부 리소스에 대해서, 이러한 세부 정보를 캡슐화하고 표시해야 하는 항목만 제공 할 수 있습니다.

왜 JSON인가?

  1. 보편성 - 모든 웹 기반 애플리케이션의 57 % 이상이 JSON, JavaScript 기반 또는 JavaScript 구성 요소를 사용합니다.
  2. Human Readable - 아주 간단한 문법과 언어를 사용하므로 소프트웨어 개발을 하는 사람을 포함하여 많은 사람이 쉽게 읽을 수 있습니다.
  3. 새 필드를 쉽게 변경하거나 추가 할 수 있습니다.

REST 디자인을 어렵게 만드는 요인은?

REST는 개발 과정에서의 설계 방식이며 특정한 스펙이나 기술이 아니기 때문에 RESTful API를 초기 설계하는 것은 어렵습니다. 마찬가지로 REST는 설계 방식이기 때문에 스탠다드한 표준이나 기관이 없고, 이에 따라 명확하거나 효율적인 디자인 규칙이 없습니다. 또한, REST에는 HTTP 프로토콜 작동 방식에 대한 해석이 포함되어있어 REST API를 설계 할 때마다 다양한 방식으로 설계할 수 있습니다.

HTTP 메소드를 사용하는 것이 REST 접근법의 핵심 이점이지만, 이는 또한 다양한 RESTful API 설계가 있다는 것을 의미합니다. 이로인해 REST를 디자인하기 어려운 상황에 놓인 개발자들을 위해, 내부에서 판단하기에 가장 중요하고 핵심적인 부분만을 추려서 가이드라인으로 정리한 내용입니다.

REST API 디자인 가이드라인

아래는 Stormpath 의 내부 개발팀이 제안하는 REST API 에 대한 디자인 가이드라인 입니다. 위에서 언급된 바와 같이 REST API 는 엄격한 규약이나 룰이 있는 것이 아닌, 설계 방식의 한 갈래 이기 때문에, 본 번역글에 포함된 가이드라인이 반드시 지켜져야 하는 룰은 아닙니다.

  1. REST API 에서는 제공하는 리소스를 세분화하지 않고 거친 데이터로 유지합니다.
    기본적으로 개발자/시스템 관리자는 사용자와 서비스의 리소스가 어떻게 상호 작용 하는지를 모릅니다. 즉, 사용자는 서비스의 리소스를 다양한 방식과 형태로 활용 가능하다는 것을 의미합니다. Stormpath의 경우 서비스의 리소스라 함은 계정, 그룹 또는 디렉토리입니다(Auth 및 계정 관리 서비스). 이러한 리소스들에 대해 사용자가 다룰 수 있는 여러 가지 작업이 있으며, 특정 리소스에 대해 작성한 하나의 메서드에 많은 변수와 기능을 추가하는 경우 관리하기가 어려울 수 있습니다. 따라서 REST API의 특정 리소스에 대한 Method를 작성할 때는 리소스 자체를 인수로 사용하는 메서드로 정의하고, 메서드에 해당 리소스에 필요한 모든 기능이 포함되도록하는 것이 좋습니다.
    (REST API 에서는 하나의 도메인(리소스)에 대하여 다양한 인수와 메서드를 작성하여 제공하는 것 보다는, 한번에 해당 도메인의 모든 정보와 기능이 포함되도록 제공하는 것이 더 나은 방향이라는 의미)
    메인 리소스 외의 다양하고 복잡한 조합(coarse grain)들은 어떻게 처리해야 할까요? collection 및 instance 리소스로 작업할 수 있습니다. collection은 유사한 리소스들이 함께 묶인 리소스이며, instance 리소스는 상위 리소스의 단일 인스턴스입니다(A를 참조하는 B들의 묶음=collection, A=상위 단일 리소스). 이렇게 하면 end point 에 영향을 주는 HTTP 동작을 사용할 수 있지만 실제로 각 인스턴스와 동작의 조합에 대해 다른 URL을 만들지는 않습니다. 이러한 설계를 통해 실제 엔드 포인트 정의에 동작을 추가하지 마십시오.
    (즉, 여러 리소스를 함께 변경하기 위한, 혹은 부모 객체를 변경하기 위한 Method를 제공하는 것보다, 부모 객체를 제공하는, 여러 리소스를 함께 제공하는 Method를 제공하는 방식으로 설계하는 것을 추천.)

  2. POST를 사용하여 부분 업데이트를 제공 및 활용
    REST API는 표준 HTTP Method에서 실행되므로 PUT 또는 POST를 사용하여 리소스를 생성하거나 갱신 할 수 있습니다. PUT을 사용하여 리소스를 만들고 POST를 사용하여 리소스를 업데이트하는 방법을 생각할 수도 있지만 실제로 POST를 둘 다 사용할 수 있습니다.

    • 왜 POST를 사용하여 리소스를 만들고 업데이트해야합니까? POST를 사용하면 PUT을 사용하는 것과 달리 호출 할 때마다 해당 데이터 자원의 모든 필드를 보낼 필요가 없기 때문입니다. 모든 업데이트에 대해 업데이트하지 않는 필드를 보내면 데이터 수정을 위한 서버 자원이 필요한 것보다 많이 소모되기 때문에 이 방식은 중요합니다. PUT 대신 POST를 사용하면 트래픽 양을 제한하면서 REST API를 측정 할 때 유용 할 수 있습니다. 또한 한 달에 수백만 또는 수억 개의 요청을 받으면 REST API의 성능에 영향을 미치므로 POST를 사용하여 트래픽을 제한하는 것이 좋습니다.
    • PUT으로 왜 똑같이 할 수 없습니까? HTTP 사양에 따라 PUT은 멱등원(하위 항목까지 모두 동일한 객체 구조를 갖는)이므로 모든 속성을 포함해야합니다. 예를 들어 description을 지정하지 않고 처음으로 응용 프로그램을 만든 다음 description을 추가하여 네 번째 호출을 보내면 상태가 서로 다를 수 있으므로 멱등원의 요구 사항을 위반하게됩니다.
  3. REST API 문서를 미디어 형식 기반의 다른 문서에 연결시켜 두어야 합니다.
    미디어 형식은 간단히 표현하여 데이터 형식이자, REST API의 사양에 대한 규칙과 정의를 담는 문서 형식입니다. REST API를 사용할 때, 클라이언트 프로그램을 만드는 경우 accept-header에 반환 할 기본 데이터 형식을 포함해야합니다. 마찬가지로 서버가 데이터를 실제로 반환되는 방법을 기록한 내용과 유형에 대한 헤더를 반환해야 합니다. 또한 사용중인 모든 데이터 유형에 parsing rules을 추가 할 수 있습니다. 예를 들어 application/JSON+foo 라는 미디어 유형을 두어 클라이언트에 이 JSON 형식의 데이터임을 알려줄 뿐만 아니라, foo 를 통해 해당 데이터를 어떻게 parsing 해야 하는지 알려줄 수 있습니다.
    따라서 클라이언트에서는 데이터를 받을 때 원하는 미디어 유형을 지정할 수 있도록 하고, 서버에서는 Content-Type 헤더를 통해 반환 될 데이터 형식을 알려주도록 합니다. 이러한 Content-Type 커스터마이징은 API를 고객에게 보다 융통성있게 만듭니다.

결론

이 글에서는 개발자 친화적인 REST API를 작성하기 위한 기본 사항은 물론 RESTful API 디자인 방식의 이점에 대해 이야기했습니다. 이것은 Les Hazelwood 의 프리젠테이션에 대한 요약 일 뿐이며 처음 30 분간의 설명이므로 나머지는 영상을 확인하십시오.


More from TooLate