.jpg)
API는 Application Programming Interface의 약자이며, Interface의 사전적 의미는 "의사소통이 가능"하도록 만들어진 "접점"을 의미한다. 즉, 서버 API는 클라이언트가 서버에 적절한 요청을 하였을 때, 그에 맞는 응답을 되돌려주는 창구를 Web을 통해 노출한 것을 말한다. 이를 이용해 요청자는 서버로부터 정보를 요청하거나 수정할 수 있다. 이 인터페이스를 사용할 때 아무런 규칙 없이는 할 수 없기에 요청과 응답에 관해 '제대로 보내고 제대로 받을 수 있는' 일종의 규약이 존재하게 된다.
서버 API를 만드는 방법론 중에는 REST API와 GraphQL API이 있다.
REST API
(Representational State Transfer)
웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식을 말한다. 이 방법론은 많은 Server API 들을 구성하기 위해 사용되었고, 현재에도 많이 사용되고 있다.
REST API에서는 HTTP 메서드를 이용해 서버와 통신한다. GET을 통해 웹 페이지나 데이터를 요청하고, POST로 새로운 글이나 데이터를 전송하거나 DELETE로 저장된 글이나 데이터를 삭제할 수 있다. 이처럼 클라이언트와 서버가 HTTP 통신을 할 때는 어떤 요청을 보내고 받느냐에 따라 메서드의 사용이 달라진다.
좋은 REST API를 작성하기 위해서는 4단계로 나뉘어진 REST 성숙도 모델이 있다. 그러나 모두 지키기에는 현실적인 한계가 있고 2단계까지만 적용해도 좋은 API 디자인이라고 볼 수 있다.
- 모델 0단계
- 단순히 HTTP 프로토콜을 사용하기만 해도 된다.
- 모델 1단계
- 개별 리소스와의 통신을 준수해야 한다.
- 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용해야 한다는 것과 요청하고 받은 자원에 대한 정보를 응답으로 전달해야 한다.
- 요청하는 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 더욱 확실하게 구분하여 사용해야 한다.
- 엔드포인트 작성 시에는 동사, HTTP 메서드, 혹은 어떤 행위에 대한 단어 사용은 지양하고, 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직하다.
- 모델 2단계
- CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둔다. 0단계와 1단계는 모든 요청을 CRUD에 상관없이 POST로 하지만 여기부터는 적절하게 요청을 나누어주어야 한다.
- GET 메서드 같은 경우는 서버의 데이터를 변화시키지 않는 요청에 사용해야 한다.
- POST 는 요청마다 새로운 리소스를 생성하고 PUT 은 요청마다 같은 리소스를 반환한다. 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 한다. 따라서 멱등한 PUT과 그렇지 않은 POST는 구분하여 사용해야 한다.
- PUT은 교체, PATCH는 수정의 용도로 구분해 사용해야 한다.
- 모델 3단계
- HATEOAS(Hypertext As The Engine Of Application State)라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용한다. 3단계의 요청은 2단계와 동일하지만, 응답에는 리소스의 URI를 포함한 링크 요소를 삽입하여 작성한다.
- 이때 응답에 들어가게 되는 링크 요소는 응답을 받은 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있다.
- 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 중요 포인트이다.
GraphQL
Graph + Query Language의 줄임말로 Query Language 중에서도 Server API 를 통해 정보를 주고받기 위해 사용하는 Query Language(정보를 얻기 위해 보내는 질의문(Query)을 만들기 위해 사용되는 Computer 언어의 일종)를 뜻하며 API를 위한 쿼리언어라고 할 수 있다.
그래프는 여러 개의 점들이 서로 복잡하게 연결되어 있는 관계를 표현한 자료구조를 뜻한다. 하나의 점은 노드(Node) 또는 정점(vertex)라고 표현하고 하나의 선은 간선(edge)라고 하는데 직접적인 관계일 때는 두 점 사이를 이어주는 선이 있고 간접적인 관계일 때는 몇 개의 점과 선에 걸쳐 이어진다. 이렇게 각 노드 간의 간선을 통해 특정한 순서에 따라 그래프를 재귀적으로 탐색할 수 있다(마인드맵 구조와 비슷해진다).
GraphQL에서는 모든 데이터가 그래프 형태로 연결되어 있다고 전제한다. 일대일로 연결된 관계도, 여러 계층으로 이루어진 관계도 모두 그래프이다. 단지 그 그래프를 누구의 입장에서 정렬하느냐(클라이언트가 어떤 데이터를 필요로 하느냐)에 따라 트리 구조를 이룰 수도 있다.
이를 통해 GraphQL은 클라이언트 요청에 따라 유연하게 트리 구조의 JSON 데이터를 응답으로 전송할 수 있다. 다시 말해 GraphQL은 REST API 방식의 고정된 자원이 아닌 클라이언트 요청에 따라 유연하게 자원을 가져올 수 있다는 점에서 엄청난 이점을 갖는다.
- Query: 저장된 데이터 가져오기 (REST의 GET과 비슷함)
- Mutation: 저장된 데이터 수정하기
- Create: 새로운 데이터 생성
- Update: 기존의 데이터 수정
- Delete: 기존의 데이터 삭제
- Subscription: 특정 이벤트가 발생 시 서버가 대응하는 데이터를 실시간으로 클라이언트에게 전송
- 클라이언트가 어떤 이벤트를 구독하면, 클라이언트는 서버와 WebSocket을 기반으로 지속적인 연결을 형성하고 유지하게 된다. 그 후 특정 이벤트가 발생하면, 서버는 대응하는 데이터를 클라이언트에 푸시해준다.
REST API vs GraphQL
REST API는 엔드포인트가 각각 나뉘어져 있기 때문에 필요없는 데이터까지 제공하는 overfetch나 필요한 정보를 충분히 제공하지 못하는 underfetch가 발생하는 일이 잦다. 또한 자원의 크기와 형태를 서버에서 결정하기 때문에 클라이언트가 직접 데이터의 형태를 수정할 수 가 없고, 클라이언트 구조 변경 시 엔드포인트의 변경 또는 데이터 수정이 필요하다.
반면 GraphQL은 하나의 엔드포인트에 요청하고 이곳에 query나 mutation을 resolver 함수로 전달해 요청에 응답하기에 정확하게 필요한 정보를 받아내기 때문에 overfetch나 underfetch 현상이 일어나지도 않는다. 마지막으로 클라이언트 구조가 바뀌어도 필요한 데이터를 결정하는 주체가 클라이언트 이기 때문에 서버에도 지장이 없게 된다.
그러나 REST API보다 학습하기 어렵다는 단점이 있으며 캐싱이 훨씬 복잡한 점 그리고 고정된 요청과 응답만 필요할 경우에는 Query로 인해 요청의 크기가 RESTful API의 경우보다 더 커진다는 단점도 존재한다.
