REST API

REST API

REST API는 Representational State Transfer의 약자로, 웹상에서 사용되는 아키텍처 스타일 중 하나이다. 이는 분산 시스템을 위한 아키텍처로, 인터넷을 통해 컴퓨터 시스템 간에 정보를 교환하는 데 사용된다. REST API를 통해, 웹 서비스 제공자는 웹 URL을 통해 리소스(데이터나 서비스)에 접근할 수 있는 인터페이스를 사용자나 애플리케이션에 제공한다. 사용자는 HTTP 요청 메서드(GET, POST, PUT, DELETE 등)를 사용하여 리소스에 대한 CRUD(Create, Read, Update, Delete) 작업을 수행할 수 있다.

RESTful API: REST 아키텍처 원칙을 엄격하게 준수하는 API를 지칭 😉

HTTP 메소드

• GET: 리소스 조회에 사용한다.
• POST: 새 리소스 생성 또는 복잡한 데이터 처리에 사용한다.
• PUT: 리소스의 전체 업데이트에 사용한다.
• PATCH: 리소스의 부분 업데이트에 사용한다.
• DELETE: 리소스 삭제에 사용한다.

주요 상태 코드

• 200 OK: 요청 성공(일반적으로 GET 및 PUT 요청에 대한 응답).
• 201 Created: 새 리소스가 성공적으로 생성됨(POST 요청에 대한 응답).
• 204 No Content: 요청은 성공했으나 응답할 콘텐츠가 없음(DELETE 요청에 대한 응답).
• 400 Bad Request: 잘못된 요청 구조.
• 401 Unauthorized: 인증되지 않은 접근.
• 403 Forbidden: 인증됐으나 권한이 없는 접근.
• 404 Not Found: 요청한 리소스를 찾을 수 없음.
• 500 Internal Server Error: 서버 내부 오류.

REST API의 주요 규칙

• 클라이언트-서버 구조(Client-Server Architecture): 클라이언트와 서버는 서로 독립적으로 동작해야 하며, 이를 통해 각각의 부분을 독립적으로 개발하고 향상시킬 수 있다.

• 상태 없음(Stateless): 모든 클라이언트 요청은 서버가 요청을 이해하고 처리하는 데 필요한 모든 정보를 포함해야 한다. 서버는 클라이언트의 상태 정보를 유지하지 않으며, 각 요청은 독립적으로 처리된다.

• 캐시 가능(Cacheable): REST API는 응답을 캐싱할 수 있어야 하며, 이를 통해 클라이언트는 반복적인 요청을 줄이고, 성능을 향상시킬 수 있다.

• 계층화된 시스템(Layered System): 클라이언트는 실제로 연결되는 서버가 최종 서버인지, 중간에 다른 서버를 통해 요청이 전달되는지 알 수 없어야 한다. 이는 시스템의 확장성을 높이는데 도움을 준다.

• 통일된 인터페이스(Uniform Interface): 리소스에 대한 통일된 인터페이스를 제공해야 한다.

• 리소스 식별(Identification of resources): 모든 리소스는 고유한 URI를 통해 식별된다.

• 표현을 통한 자원 조작(Manipulation of resources through representations): 클라이언트는 리소스의 표현을 통해 해당 리소스를 조회하거나 수정할 수 있다.

URI 설계

• 명사 사용: URI는 리소스를 나타내며, 리소스는 명사로 표현되어야 한다. 예를 들어, /users, /books 등이 있다.
• 복수형 사용: 복수형을 사용함으로써 API의 일관성을 유지하고, 해당 엔드포인트가 단일 객체가 아닌, 관련 객체의 집합을 다룬다는 것을 더욱 분명히 표현한다.
  • GET /users: 사용자 목록 조회
  • POST /users: 새 사용자 추가
  • GET /users/{id}: 특정 사용자 조회
  • PUT /users/{id}: 특정 사용자 정보 업데이트
  • DELETE /users/{id}: 특정 사용자 삭제
• 계층 구조 사용: 리소스 간의 관계를 나타내기 위해 계층적 구조를 사용한다. 예: /users/{userId}/orders는 특정 사용자의 주문을 나타낸다.
• 소문자 사용: URI는 대소문자에 민감하기 때문에, 일반적으로 소문자 사용을 권장한다.
• 하이픈(-) 사용: 가독성을 높이기 위해 단어 구분에는 하이픈을 사용한다. 예: /user-profiles
• 필터링, 정렬, 페이징
  • 필터링: 클라이언트가 특정 조건을 만족하는 리소스만 요청할 수 있게 한다. 예: /users?role=admin
  • 정렬: 결과의 정렬 순서를 지정할 수 있다. 예: /users?sort=createdAt_desc
  • 페이징: 대용량 데이터 처리를 위해 결과를 페이지로 나누어 제공한다. 예: /users?page=2&limit=50

URI, URL, URN 차이점

• URI (Uniform Resource Identifier, 통합 자원 식별자): 인터넷 상의 자원을 식별하기 위한 문자열의 구조이다. URI는 URL과 URN을 포함하는 더 넓은 개념으로, 모든 URL과 URN은 URI이다.

• URL (Uniform Resource Locator, 통합 자원 위치 지정자): 인터넷 상의 자원이 실제로 위치한 곳을 나타내는 주소이다. URL은 자원에 접근하기 위한 구체적인 위치와 방법을 제공한다. 예를 들어, ‘http://www.example.com’은 웹 상의 특정 페이지를 가리키는 URL이다.

• URN (Uniform Resource Name, 통합 자원 이름): 자원을 위치에 관계없이 이름만으로 식별하는 데 사용된다. URN은 자원이 어디에 존재하는지, 어떻게 접근해야 하는지를 나타내지 않고, 자원을 고유하게 식별하는 데 중점을 둔다. 예를 들어, ISBN(국제 표준 도서 번호)는 책에 대한 URN으로 사용될 수 있다.