RESTful API 설계를 위한 10가지 가이드

RESTful(Representational State Transfer) API는 2000년도에 로이 필딩의 박사학위 논문에서 최초로 소개되었습니다. 로이 필딩은 HTTP 사양의 주요 저자 중 한 사람으로 HTTP/1.1의 설계와 관련된 작업 과정에서 웹 아키텍처와 REST의 개념을 발전시켰습니다. REST는 자원(Resource)을 중심으로 설계된 아키텍처로, HTTP와 URI 기반으로 자원에 접근할 수 있도록 하는 인터페이스입니다. HTTP 프로토콜로 API만들 때 URL(URI)로만 API의 역할을 알 수 있게 설계한 것을 RESTful API라고 합니다.

출처_https://danielmiessler.com/p/difference-between-uri-url/

 

예를 들어, 다음과 같은 URL이 있을 때, https://search.shopping.naver.com/best/today?rankedDate=20220922

사용자는 이 URL을 보고 네이버 회사의 쇼핑 도메인의 조회 URL이며, 그 중에서 2022년 9월 22일 베스트 랭킹 조회 URL인 것을 알 수 있습니다.

 

REST API란 REST라는 아키텍처의 제약 조건을 준수한 API를 뜻합니다. 이 REST 제약 조건을 준수한 API를 Restful 하다고 표현합니다. REST 제약 조건은 REST 아키텍처의 기본 원칙으로, 시스템의 구조와 동작 방식에 대한 요구 사항입니다.

 

REST 아키텍처 제약 조건

• 클라이언트-서버 구조: 클라이언트와 서버의 독립적 설계
• 무상태성: 각 요청은 독립적이며, 서버는 클라이언트의 상태를 저장하지 않음
• 캐시 가능성: 응답은 캐시 가능하며, 클라이언트는 캐시 여부를 알 수 있어야 함
• 계층화 시스템: 클라이언트가 여러 중간 서버를 통해 서버와 통신할 수 있음
• 일관된 인터페이스: 자원에 대한 접근 방식이 일관되어야 함
• 자원 기반: 자원이 URI로 식별되고, HTTP 메소드를 통해 접근됨

 

RESTful API의 10가지 원칙은 설계 가이드라인으로, RESTful API를 만들 때 고려해야 할 사항들입니다. 이 원칙들은 API의 일관성, 확장성, 효율성 및 유지보수성을 높이기 위한 권장 사항입니다.

 

RESTful API 설계 10가지 원칙

• 자원 기반 설계: API는 자원(리소스)을 중심으로 구성되어야 하며, 각 자원은 고유한 URI로 식별됩니다. 예를 들어, https://api.example.com/books/1는 도서 자원을 식별하기 위한 고유한 주소입니다. 이 URI를 통해 클라이언트는 도서 목록에 접근할 수 있고 각각의 도서는 데이터베이스에서 고유한 ID(예: 1, 2, 3 등)를 갖습니다. 이 ID는 도서를 유일하게 식별하는 데 사용되며, 특정 도서에 접근할 때 URI에 포함될 수 있습니다.
• HTTP 메소드 사용: CRUD 작업에 대해 적절한 HTTP 메소드를 사용해야 합니다. 
  • GET /books - 모든 도서 조회
  • POST /books - 새로운 도서 추가
  • PUT /books/1 - ID가 1인 도서 정보 업데이트
  • DELETE /books/1 - ID가 1인 도서 삭제
• 무상태성: 클라이언트는 매 요청에 필요한 모든 정보를 포함해야 합니다. 예를 들어, 도서를 추가할 때, 모든 필드(제목, 저자, 연도 등)를 요청 본문에 포함해야 합니다.
• 표현 형식: 자원은 JSON, XML 등 다양한 표현 형식으로 클라이언트에 전달될 수 있습니다. 

// JSON 형식 예시
{
  "id": 1,
  "title": "The Great Gatsby",
  "author": "F. Scott Fitzgerald"
}

• 일관된 URI 설계: URI는 자원을 명확하게 표현해야 하며, 명명 규칙이 일관되어야 합니다.
  • GET /books - 모든 도서
  • GET /books/1 - ID가 1인 도서
  • URI는 복수형을 사용하여 일관성을 유지합니다.
• 에러 처리: 오류 발생 시 적절한 HTTP 상태 코드와 오류 메시지를 반환해야 합니다. 예를 들어, { "error": "Book not found" }의 상태 코드는 404 Not Found입니다.
• 링크 사용: HATEOAS(Hypermedia as the Engine of Application State)를 활용하여 응답에 관련된 자원에 대한 링크를 포함함으로써 클라이언트가 다음 수행할 수 있는 작업을 쉽게 찾을 수 있게 합니다.

{
  "id": 1,
  "title": "The Great Gatsby",
  
  // links 배열: 클라이언트가 사용할 수 있는 추가적인 URI 링크들
  "links": [
    {
      "rel": "self", 
      // rel(Relationship): 각 링크의 관계 
      // self: 클라이언트는 이 링크를 사용하여 해당 자원(도서)의 상세 정보를 다시 요청할 수 있습니다.
      "href": "https://api.example.com/books/1" // 실제 요청을 보내야 할 URL
    },
    {
      "rel": "update",
      // update: 클라이언트는 이 링크를 통해 도서의 정보를 수정할 수 있는 요청을 보낼 수 있습니다.
      "href": "https://api.example.com/books/1"
    }
  ]
}

• 버전 관리: API의 버전을 URI에 포함하여 관리합니다. 예를 들어, https://api.example.com/v1/books는 첫 번째 버전을 나타냅니다.
• 캐시 가능성: 서버 응답에 캐시 제어 헤더를 포함하여 클라이언트가 응답을 캐시할 수 있도록 합니다.

Cache-Control: public, max-age=3600
// public: 응답이 모든 사용자에게 캐시될 수 있음을 의미합니다.
// max-age=3600: 캐시된 응답이 최대 3600초(즉, 1시간) 동안 유효하다는 것을 의미합니다. 
// 이 시간 동안 클라이언트는 서버에 요청을 보내지 않고도 캐시된 응답을 사용할 수 있습니다.

• 보안 고려: API에 인증 및 권한 관리 기능을 포함해야 합니다. API는 HTTPS를 통해 안전한 데이터 전송을 보장하며, Bearer Token을 사용하여 인증합니다. 클라이언트는 요청 헤더에 다음과 같은 정보를 포함합니다.

Authorization: Bearer <token>

 

 

RESTful API 설계를 위한 업계 표준 사양을 나타낸 것을 OAS(OpenAPI Specification)라고 합니다. OAS는 json 이나 yml 형식으로 기술해야 하며 OAS파일을 읽어서 디플로이 해주는 도구(ex) swagger-ui)를 사용하면 아래와 같이 브라우저에서 편리하게 API 문서를 볼 수 있습니다.

 

 

Swagger란 OAS를 위한 프레임워크입니다. Swagger는 OpenAPI 스펙을 맞춘 api-docs를 이용하여 html 페이지로 문서화해주는 프레임워크로, RESTful API 설계 및 문서화에 도움을 주며 다음과 같은 기능이 있습니다. 

• API 디자인: Swagger-editor를 통해 API를 문서화하고 빠르게 명세할 수 있습니다. 
• API Development: Swagger-codegen을 통해 작성된 문서로 SDK를 생성하여 빌드 프로세스를 간소화할 수 있습니다.
• API Documentation: Swagger-UI를 통해 작성된 API를 시각화시켜줍니다.
• API Testing: Swagger-Inspector를 통해 API를 시각화하고 빠른 테스트를 진행할 수 있습니다.
• Standardize: Swagger-hub를 통해 API 정보를 공유할 수 있습니다.

 

RESTful API는 URI를 통해 자원을 정의하고, HTTP 메소드를 통해 자원에 대한 작업을 수행하는 표준화된 방식이기 때문에 모든 웹 환경에서 쉽게 구현할 수 있다는 장점과 JSON, XML, HTML 등 다양한 데이터 형식을 지원하여 클라이언트와 서버 간의 상호작용을 유연하게 만들고, 클라이언트와 서버 간의 독립성을 유지하여, 서로 다른 팀에서 독립적으로 개발할 수 있다는 등의 장점이 있습니다. 이러한 이유들로 RESTful API는 IT 회사들이 요구하는 필수 기술 중 하나가 되었으며, 경쟁력 있는 개발자가 되기 위해서는 이 기술에 대한 깊은 이해와 경험이 필요한 것 같습니다.