TIL - RESTful API

eslerkang·2021년 12월 8일
0

TIL - Today I Learned

목록 보기
10/19
post-thumbnail

REST

API(어플리케이션 프로그래밍 인터페이스)는 어플리케이션, 디바이스가 서로 연결하여 통신하는 방법을 정의하는 규칙 모음이다.
즉 이 포스트의 제목과 방금의 설명을 종합해보면 REST API는
REST인 API라고 생각할 수 있을 것이다(또한 실제로도 REST라는 규칙을 준수하는 API라는 뜻으로 RESTfull API라고도 불린다). 그렇다면 REST는 무엇일까?

Dr. Roy Fielding가 2000년에 박사학위 논문에서 정의한 REST는 소프트웨어 아키텍처의 한 형식이다. 엄격한 의미로 REST는 네트워크 아키텍처 원리의 모음으로 네트워크 아키텍처 원리란 자원을 정의하고 자원에 대한 주소를 지정하는 방법 전반을 일컫는다. 간단한 의미로는, 웹 상의 자료를 HTTP위에서 SOAP이나 쿠키를 통한 세션 트랙킹 같은 별도의 전송 계층 없이 전송하기 위한 아주 간단한 인터페이스를 말한다.
출처(위키백과 - REST)

그렇다면 REST의 규칙은 무엇이고 어떤 규칙들을 지켜야 REST한 API를 만들 수 있을까?

RESTful

  • 균일한 인터페이스. 요청이 어디에서 오는지와 무관하게, 동일한 리소스에 대한 모든 API 요청은 동일하게 보여야 합니다. REST API는 사용자의 이름이나 이메일 주소 등의 동일한 데이터 조각이 오직 하나의 URI(Uniform Resource Identifier)에 속함을 보장해야 합니다. 리소스가 너무 클 필요는 없지만, 이는 클라이언트가 필요로 하는 모든 정보를 포함해야 합니다.
  • 클라이언트-서버 디커플링. REST API 디자인에서, 클라이언트와 서버 애플리케이션은 서로 간에 완전히 독립적이어야 합니다. 클라이언트 애플리케이션이 알아야 하는 유일한 정보는 요청된 리소스의 URI이며, 이는 다른 방법으로 서버 애플리케이션과 상호작용할 수 없습니다. 이와 유사하게, 서버 애플리케이션은 HTTP를 통해 요청된 데이터에 전달하는 것 말고는 클라이언트 애플리케이션을 수정하지 않아야 합니다.
  • Stateless. REST API는 stateless입니다. 이는 각 요청에서 이의 처리에 필요한 모든 정보를 포함해야 함을 의미합니다. 즉, REST API는 서버측 세션을 필요로 하지 않습니다. 서버 애플리케이션은 클라이언트 요청과 관련된 데이터를 저장할 수 없습니다.
  • 캐싱 가능성. 가급적이면, 리소스를 클라이언트 또는 서버측에서 캐싱할 수 있어야 합니다. 또한 서버 응답에는 전달된 리소스에 대해 캐싱이 허용되는지 여부에 대한 정보도 포함되어야 합니다. 이의 목적은 서버측의 확장성 증가와 함께 클라이언트측의 성능 향상을 동시에 얻는 것입니다.
  • 계층 구조 아키텍처. REST API에서는 호출과 응답이 서로 다른 계층을 통과합니다. 일반적으로는, 클라이언트와 서버 애플리케이션이 서로 간에 직접 연결된다고 가정하지 마세요. 통신 루프에는 다수의 서로 다른 중개자가 있을 수 있습니다. REST API는 엔드 애플리케이션 또는 중개자와 통신하는지 여부를 클라이언트나 서버가 알 수 없도록 설계되어야 합니다.
  • 코드 온디맨드(옵션). REST API는 일반적으로 정적 리소스를 전송하지만, 특정한 경우에는 응답에 실행 코드(예: Java 애플릿)를 포함할 수도 있습니다. 이러한 경우에, 코드는 요청 시에만 실행되어야 합니다.

출처(IBM - rest apis)

와 같은 조건을 잘 준수하는 것이 REST한 것이라고 IBM에서 설명하고 있다. 그렇다면 차근차근 위의 복잡해보이는 저 규칙들이 무엇을 의미하는지 간단히 설명해보겠다.


REST의 중요한 규칙을 정리해보자면 아래의 두가지와 같다고 생각할 수 있다.

  • URI은 정보/자원을 표현해야한다.
  • 정보/자원에 대한 행위는 HTTP Method(GET/POST/DELETE/PATCH 등)로 표현한다.

1. URI은 정보/자원을 표현해야한다.

이 규칙은 URI은 어떠한 행위, 동작을 담지 않고 접근하고 있는 자원에 대해서만 쓰여있어야 한다는 뜻이다. 즉

GET /products/delete/1 --> 동작을 포함하고 있으니 X
DELETE /products/1 --> 과 같이 표현해야함

위의 URI와 같이 어떤 동작을 하는지에 대해서는 명시하지 않고 어떤 자원에 접근하는지에 대해서만 명시해줘야 한다는 뜻이다.

2. 정보/자원에 대한 행위는 HTTP Method(GET/POST/DELETE/PATCH 등)로 표현한다.

위에서 잠깐 등장한 것과 같이 자원에 대한 어떤 행위를 나타낼때는 /products/delete와 같이 나타내지 않고 HTTP의 Method로 나타내야 한다는 규칙이다.

  • GET 메서드는 특정 리소스의 표시를 요청합니다. GET을 사용하는 요청은 오직 데이터를 받기만 합니다.
  • HEAD 메서드는 GET 메서드의 요청과 동일한 응답을 요구하지만, 응답 본문을 포함하지 않습니다.
  • POST 메서드는 특정 리소스에 엔티티를 제출할 때 쓰입니다. 이는 종종 서버의 상태의 변화나 부작용을 일으킵니다.
  • PUT 메서드는 목적 리소스 모든 현재 표시를 요청 payload로 바꿉니다.
  • DELETE 메서드는 특정 리소스를 삭제합니다.
  • CONNECT 메서드는 목적 리소스로 식별되는 서버로의 터널을 맺습니다.
  • OPTIONS 메서드는 목적 리소스의 통신을 설정하는 데 쓰입니다.
  • TRACE 메서드는 목적 리소스의 경로를 따라 메시지 loop-back 테스트를 합니다.
  • PATCH 메서드는 리소스의 부분만을 수정하는 데 쓰입니다.

출처(Mozilla - HTTP Method)

위와 같이 HTTP Method에는 다양한 것들이 있으며 어떤 Method로 입력을 받아도 원하는 동작을 다 행할 수는 있겠지만 저 Method들의 목적에 맞는 행위만을 하는 것이 RESTful하다고 할 수 있다. 저 중 PUT/PATCH는 비슷해보이는데 PUT은 목적 자원의 모든 정보를 변경하는 것이고 PATCH는 목적 자원의 특정 정보만을 변경한다는 차이가 있다.

URI 설계 시 주의사항

  1. 슬래시(/)는 계층 관계를 나타낼 때 사용한다. 즉 /categories/products와 같이 계층을 나눌 때 사용하면 된다.
  2. URI 마지막 문자로 슬래시(/)를 포함하지 않는다. URI에서 슬래시는 계층을 나누는 것이고, URI의 모든 단어는 고유한 식별자로써 작용해야 하므로 혼돈을 주지 않기 위해 URI의 가장 마지막에는 슬래시를 사용하지 않는다.
    /products/와 같이 사용할 수 없고 /products와 같이 작성해야 한다.
  3. URI를 쉽게 읽기 위해 긴 URI경로를 사용하게 된다면 하이픈(-)을 사용해 가독성을 높일 수 있다.
  4. 밑줄(_)은 URI에 사용하지 않는다. 밑줄은 폰트에 따라 달라질 수 있지만 주소창에 입력하여 볼 때 잘 보이지 않는다는 문제가 발생할 수 있다. 이런 문제를 피하기 위해 밑줄 대신 하이픈(-)을 사용하는 것이 좋다.
  5. URI 경로에 대문자 사용은 피해야한다. RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문에 각 단어가 고유한 식별자로 작용하는 URI에서는 대소문자로 인해 같은 리소스가
  6. REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다. 확장자를 표현할 때는 Accept header를 사용한다.

와 같은 방법을 통해 URI를 좀 더 RESTful하게 설계할 수 있다. 이 외에 /products/people와 같이 계층 간의 즉, 제품과 사람 간의 관계를 알기 어려우면 /products/like/people과 같이 계층 간의 관계를 나타낼 수 있다. 또한 어떤 집단을 나타내는 경우(products, sports) 복수로 작성함으로써 특정 자원들을 가리킨다는 것을 명시할 수 있다.

profile
Surfer surfing on the dynamic flow of the world

0개의 댓글