[ASAC 06] REST API

이 글은 ASAC 06기를 수강하며 강의 자료 참고 및 추가 자료 수집을 통해 작성된 글입니다.

REST API

API 는 Application Programming Interface 의 약자로, 웹 애플리케이션 개발에서 웹 데이터를 전달하는 정해진 구조를 의미한다.

REST(Representative) API 표현 원칙을 준수하여 만든 API를 의미한다.
REST 철학을 적용하여 API를 설계하는 것을 RESTful 하다고 한다.

• REST
  웹에 존재하는 모든 자원에 고유한 URL 을 부여하여 활용하는 것.
  즉, 데이터 교환 방식을 정의한 것
• RESTful
• URI가 인간의 문장으로 치환이 되어서 그 자체로 어떤 행위를 하는지 명확히 알 수 있다. 디자인 패턴처럼 REST를 잘 사용할 수 있는 규칙을 만들어 그 기준으로 RESTful 한지 판단한다.

REST API 설계 고려사항

다음은 REST API를 설계하기 위한 고려사항들이다.

1. method
   동사 -> 어떤 행위를 할 것인지
2. URI(URL)
   명사(목적어) -> 어떤 자원에 대해서?
   사람의 문장 그대로 요청을 치환
3. 반환 형태(json, xml)
4. 상태 코드

RESTful API를 설계하기 위해서는 API의 행위에 맞는 메서드를 선택하고,

어떤 자원을 요청하는지에 대해서 URI만 보고도 알 수 있도록 URI 규칙을 따라야 한다.

 

method, URI는 REST API의 요청과 응답을 위해서 사용된다.

method

HTTP 전송 메서드는 행위(CRUD)를 명시한다.

행위	HTTP 전송 METHOD
CREATE	POST
READ	GET
UPDATE	PUT, PATCH
DELETE	DELETE

URI

• URL -> Uniform Resource Location. 장소
  ex) https://aaron.com
• URI -> Uniform Resource Identifier. 장소 내 지정. 목적어를 꾸미는 모든 것을 포함
  ex) https://aaron.com/users/aaron/favorite-things

URL과 URI를 구분 없이 혼용하는 경우가 많지만, 특정한 데이터를 요청하기 위한 구체적인 장소 내 지정은 URI 이다.

URI는 넓은 범위에서 좁은 범위로 나아간다.
URI의 구성은 다음과 같다.

*/ collection / document / store / controller
*

• Collection
  Document의 상위 디렉토리 리소스이다.
  ex) People
• Document
  Collection 내 단일 리소스이다.
  ex) Person
  컴퓨터에서 일반적으로 뭔가를 지칭할 때는 자연어 대신 id를 사용한다. 자연어로 정의된 Document의 이름은 바뀔 가능성이 있기 때문에, unique한 id를 사용해 Document를 식별한다.
• Store
  Document의 특정 형태. 하위 리소스이다.
  ex) Person's favorites
• Controller
  표현 가능 method(CRUD) 제외한 행위 명시. 필요에 따라서 URI 마지막에 표현한다.
  동사(method)에 대한 꾸밈어이다. -> 어떤 형태의 API인가?
  ex1) /people/12/register - 12번 Person에 대한 회원 등록. (POST 표현 강화)
  ex2) 검색에 대한 api는 마지막에 search 명시
  • 일반적으로는 method로 충분할 것 같지만 method 의미를 강화하기 위해서 사용하는 경우도 있다. 필수적이지 않다.

웹에 있어서는 은탄환이 없다.
하나의 올바른 답이 없기 때문에 API를 RESTful하게 설계하는 것은 권장되지만 반드시 위의 규칙을 따라야하는 것은 아니다. 더 좋은 방법이 있다면 해당 방법을 사용하더라도 무관하다.

URI 변수

URI에서 카테고리는 언제든 달라질 수 있다. 예를 들어 Document의 경우에도 상품마다 다른 id를 가진다. 이렇게 URI에서 매번 달라지는 값은 변수 로 처리한다.

ex) /users/{id}/favorite-song
위 예시에서는 id가 URI 변수이다.

URI(Path)에 들어가는 변수 종류는 두 가지가 있다.

1. path variable : path 상의 변수
   ex) /hello/world
2. query parameter : 물음표 뒤의 변수. 쿼리를 위함
   ex) /hello?next=world
   쿼리 파라미터는 물음표 뒤에서 key=value 형식으로 작성되며, 여러 개의 쿼리 파라미터를 쓰는 경우 , 로 구분한다.

웹 데이터의 형식

웹 데이터는 객체 형식으로 반환된다.
일반적으로 json, xml 등의 형식을 가진다.

객체와 클래스

• 객체 : 필드, 메서드로 구성됨.
• 클래스 : 필드, 메서드, 생성자로 구성됨. 생성자는 클래스가 객체를 만들 때 사용하는 특별한 메서드로, 객체에는 일반적으로 생성자가 존재하지 않는다.

메서드의 존재 목적은 캡슐화이다.
메서드를 사용하면 필드를 외부에 노출하지 않으며(데이터를 보호하며) 값을 조작할 수 있다. (get, set, etc...)

Http Response Status

• 10x : 정보성 응답 (코드 뿐만 아니라 설명하는 긴 응답)
• 20x : 성공.
• 30x : 리다이렉션
• 40x : 권한 없음 혹은 잘못된 접근
• 50x : 서버 내부 문제

만약 서버 측 문제가 발생했을 때 400번대 응답 코드를 반환하도록 했다면, 실제로 서버 측 문제가 발생했을 때에 오류를 바로잡기 매우 힘들 것이다.

오류 발생 시 문제 파악과 해결을 위해서 반드시 알맞은 상태코드를 반환하도록 해야한다.

컨트롤러

컨트롤러 는 API의 집합이다. 클라이언트의 요청에서 가장 먼저 요청을 받아들일지 결정하고, 웹 리소스를 반환하는 역할을 한다.

1 도메인(서비스) - 1 컨트롤러 - N API 매핑

1개의 도메인(서비스)에는 1개의 컨트롤러가 연결된다. 그리고 1개 컨트롤러에는 1개의 URI가 연결된다. URI 변수에 따라 구분되지만 같은 기능을 하는 N개 API가 하나의 컨트롤러에 연결된다.