REST API

인화·2025년 9월 16일
RESTREST APIapi 명세서

캡스톤

목록 보기
1/2

 현재 캡스톤디자인 수업을 듣고 있는데, 프로젝트를 시작하기 전, 여러 설계 문서를 작성하던 도중 다른 학생들이 API 명세서가 무엇인지, API가 무엇인지, 그중에서도 REST API가 무엇인지, Restful한 설계가 무엇인지 등 이러한 개념들을 잘 모른다는 사실을 알게 되었습니다. 그래서 그런 학생들에게 공유하기 위해 한 번 자료들을 정리해 보았습니다.

 도움이 될진 모르겠지만 저와 같은 상황에 있으신 분들에게 도움이 되길 바랍니다. 또한, 아래 사진의 API 명세서는 제가 틀을 만들고 작성한 것인데, 템플릿이 필요한 분들은 댓글 남겨주시면 개인적으로 공유 드리겠습니다.

API 명세서란?

  • API 명세서는 API가 어떤 용도로 만들어졌는지, 어떤 유형의 API인지, 어떤 요청 방식을 사용하는지 등을 설명하는 문서를 의미합니다.
  • 예시 - User 정보에 대한 API 명세

REST의 이해

REST의 개념

  • 서버에서 이야기하는 API는 주로 REST API를 의미하며, 여기서 REST는 HTTP URI를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation(Create, Read, Update, Delete)을 적용하는 것을 의미합니다.
    - 예를 들면 다음과 같습니다. 이렇게 GET, POST, PUT, DELETE와 같은 HTTP Method와 /users, /users/{id}와 같은 HTTP URI를 통해 자원을 명시합니다. (좀 더 쉽게 표현을 해보자면 자원을 이름으로 구분하여 해당 자원의 상태를 주고 받는 모든 것을 REST라고 한다고 이해하면 됩니다.)
    - GET /users → 사용자 목록 조회
    - POST /users → 사용자 생성
    - PUT /users/{id} → 사용자 정보 수정
    - DELETE /users/{id} → 사용자 삭제

REST의 구성 요소

REST는 자원(Resource), 행위(Verb), 표현(Representation of Resource)으로 구성됩니다.

  • 자원 (Resource) : 모든 자원에는 고유한 ID가 존재하고, 이 자원은 서버에 존재하며, 자원을 구분하는 ID는 /users/{id} 와 같은 HTTP URI입니다. 사용자는 URI를 통해 자원을 지정하고, 해당 자원의 상태에 대한 조작을 서버에 요청합니다.
  • 행위 (Verb) : 행위는 HTTP 프로토콜의 Method를 사용하고, HTTP 프로토콜은 GET, POST, PUT, PATCH, DELETE의 Method를 제공합니다.
    • GET (Read) : 정보 요청, URI가 가진 정보 검색을 위해 서버에 요청
    • POST (Create) : 정보 입력, 클라이언트에서 서버로 전달하려는 정보 전송
    • PUT (Update) : 정보 업데이트. 주로 내용을 갱신하기 위해 사용 (데이터 전체 수정)
    • PATCH (Update) : 정보 업데이트. 주로 내용을 갱신하기 위해 사용 (데이터 일부 수정)
    • DELETE (Delete) : 정보 삭제
  • 표현 (Representation of Resource) : Client와 서버가 데이터를 주고 받는 형태로, JSON, XML, TEXT, RSS 등이 존재하며, 보통 사람과 기계가 모두 읽기 쉬운 JSON 혹은 XML을 통해 데이터를 주고 받습니다.
  • 이렇게, REST는 HTTP URI를 통해 Client와 Server가 통신하는 방식 중 하나입니다.

REST의 특징

1) Uniform (유니폼 인터페이스)

  • URI로 지정한 Resource에 대한 요청을 통일되고, 한정적으로 수행하는 아키텍처 스타일을 의미합니다.\
  • HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하며, Loosely Coupling(느슨한 결합) 형태를 가지므로 특정 언어나 기술에 종속되지 않습니다.

2) Stateless (무상태성)

  • HTTP 프로토콜은 Stateless Protocol이므로 REST 역시 무상태성을 지니므로 Client의 Context를 서버에 저장하지 않습니다. 따라서 세션과 쿠키와 같은 Context 정보를 신경쓰지 않아도 되므로 구현이 단순해집니다.
  • 하지만, 서버는 각각의 요청을 완전히 별개의 것으로 인식하고 처리하므로 요청마다 인증 등의 정보를 다시 보내야 한다는 단점이 존재합니다.
  • 각 API 서버는 Client의 요청만을 단순 처리하고, 이전 요청이 다음 요청의 처리에 연관되어선 안 됩니다. (단, DB에 의해 바뀌는 것은 허용함)
  • 서버의 처리 방식에 일관성을 부여해 서비스의 자유도가 높아집니다.

3) Cacheable (캐시 가능)

  • 웹 표준 HTTP 프로토콜을 그대로 사용하므로 웹에서 사용하는 기존의 인프라를 그대로 활용할 수 있기에 HTTP가 가진 기능 중 하나인 캐싱 기능을 적용할 수 있고, 이는 Last-Modified Tag 또는 E-Tag를 통해 구현합니다.
  • 이로 인해 대량의 요청을 효율적으로 처리할 수 있다는 장점이 존재합니다.

4) Self-descriptiveness (자체 표현 구조)

  • 요청 메시지만 보고도 쉽게 이해할 수 있는 자체 표현 구조로 되어있습니다.

5) Client - Server 구조

  • 자원이 있는 쪽이 Server, 자원을 요청하는 쪽이 Client가 되어 REST Server는 API를 제공하고 비즈니스 로직 처리 및 저장을 책임지고, Client는 사용자 인증이나 Context 등을 직접 관리하고 책임집니다.
  • 이를 통해 역할을 확실히 구분하고, 서로 간의 의존성을 줄일 수 있습니다.

6) 계층형 구조

  • REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조 상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간 매체를 사용할 수 있습니다.
  • 이때, Client는 Server와 직접 통신하는지, 중간 서버와 통신하는지 알 수 없습니다.

REST API

  • REST API란, REST를 기반으로 서비스 API를 구현한 것으로 현재 대부분의 서비스에선 REST API를 제공합니다.
  • API는 항상 메뉴얼도 함께 제공되어야 하며, 저희가 이러한 API 명세서를 작성하는 이유도 API 명세서를 작성하지 않고 개발을 시작하면 개발자가 API의 엔드포인트, 요청과 응답 형식, 데이터 유형, 인증 방법 등을 이해하는 데 많은 시간을 쏟게 됩니다. 그래서 이러한 일들을 미연에 방지하고자 항상 프로젝트 개발을 시작하기 전, API 명세서를 작성하는 것이 좋습니다.

REST API의 목적

  • RESTful한 API를 구현하는 근본적인 목적은 성능 향상이 아닌, '일관적인 컨벤션을 통한 API의 이해도 및 호환성을 높이는 것'임.
  • REST API의 설계 규칙을 올바르게 지키지 못한 시스템은 REST API를 사용하였지만 RESTful 하지 못한 시스템이라고 할 수 있음. (REST는 아키텍처 스타일, REST API는 이를 올바르게 지킨 API를 의미하므로 이렇게 표현합니다.)

REST API의 설계 원칙

  1. URI는 정보의 리소스를 표현해야 한다.
    a. 행위에 대한 표현이 아닌 리소스 표현하는데 중점을 두어야 한다.
    b. 리소스명은 동사보다는 명사를 사용한다.
    c. 예시 : DELETE /members/1 (O) GET /members/delete/1 (X)
  2. 리소스에 대한 행위는 HTTP Method로 표현한다.
  3. 슬래시 구분자(/)는 계층 관계를 나타내는데 사용한다.
  4. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
    a. URI를 쉽게 읽고 해석하기 위해, 불가피하게 긴 URI 경로를 사용하게 된다면 하이픈을 사용해 가독성을 높일 수 있다.
  5. 하이픈(-)은 URI 가독성을 높이는데 사용할 수 있다.
  6. 언더바(_)는 URI에 사용하지 않는다.
  7. URI 경로에는 소문자를 사용한다.
    a. 대소문자에 따라 다른 리소스로 인식하기 때문이다.
  8. 파일 확장자는 URI에 포함시키지 않는다.
    a. REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다. 대신 Accept header를 사용한다.
       // REST 적용 예시
   http://restapi.example.com/members/soccer/345/pthoto.jpg (X)
   GET /members/soccer/345/photo HTTP/1.1 (O)
   	Host: restapi.example.com
   	Accept: image/jpg

HTTP 상태 응답 코드

 API 요청의 성공 여부를 알기 위해 상태 코드에 대해 알아두는 게 좋습니다. 앞으로 개발을 하면서 많이 보게 될 응답 코드이니 다들 참고하시면 좋을 것 같습니다.

  • 200 OK : 요청이 성공적으로 처리됨
  • 201 Created : 새로운 리소스가 생성됨
  • 204 No Content : 요청이 성공했으나 반환할 데이터가 없음
  • 400 Bad Request : 잘못된 요청
  • 401 Unauthorized : 인증 실패
  • 404 Not Found : 요청한 리소스를 찾을 수 없음
  • 500 Internal Server Error : 서버 내부에서 오류가 발생하여 요청을 처리할 수 없음
  • 503 Service Unavailable : 서버가 현재 요청을 처리할 수 없음을 나타냄 (e.g. 서버 과부하, 유지보수)
  • 2xx : 성공
  • 4xx : 클라이언트 측에서의 요청 오류
  • 5xx : 서버 측에서의 요청 처리 오류

 응답 코드에 따라 다른 Response를 반환할 수 있도록 API 명세서 작성 시 다음과 같은 형식으로 작성할 수도 있습니다.

profile
인화
얼렁뚱땅 바보 학부생...
다음 포스트

GitHub

0개의 댓글