코로 넘어져도 헤딩만 하면 그만
REST API, Open API 본문
앞에서 웹 어플리케이션이 HTTP 메서드를 사용해서 서버와 통신한다는 사실을 알아보았습니다!
이러한 소통을 위해서 간단하고, 일관적이며, 사용이 간편하게 해주는 규칙이 존재합니다. 요청과 응답을 할 때 바람직하게 보내고 받을 수 있도록 규약이 존재하는 것입니다. 안그러면 각자 양식이 달라 몹시 혼란스러워질 테니까요.
🎈REST API?
REST (Representational State Transfer) API 는 웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식을 의미합니다. HTTP 프로토콜을 기반으로 요청과 응답에 따라 리소스를 '잘' 주고받기 위해서는 알아보기 쉽게 작성된 규약이 필요한데, 바로 이 역할을 하는 것이 REST API인 셈이죠.
REST API를 작성할 때는 지켜야 할 규칙들이 있는데요. 레오나르드 리차드슨(Leonard Richardson)은 REST API를 잘 적용하기 위한 4단계 모델을 만들었습니다. 각 단계의 조건에 만족할수록 REST API에 가까워집니다.
REST 성숙도 모델은 0~3단계, 즉 총합 4단계로 이루어져요. 하지만, 엄밀하게 말해 3단계까지 지키긴 어렵기 때문에 2단계까지만 잘 적용해도 좋은 API 디자인이라고 할 수 있습니다. 이 경우는 HTTP API라고 부르기도 합니다.
🚩0단계
HTTP 프로토콜을 사용하기만 해도 됩니다.
0단계에서는 HTTP만 사용할 뿐 웹 메커니즘은 전혀 사용되지 않습니다. REST API의 출발점인 이 단계에서는 리소스 구분 없이 설계된 HTTP API라고 할 수 있지만, 아직 REST API라고 부를 수는 없습니다.
모든 요청에서 엔드 포인트로 /appointment를 사용합니다.
🚩1단계
개별 리소스(Resource)와 통신합니다.
0단계처럼 모든 요청을 단일한 엔드 포인트로 보내지 않는다는 큰 차이를 가집니다. 모든 자원은 개별 리소스에 맞는 엔드 포인트(Endpoint)를 사용해야 하며 요청하고 받는 자원에 대한 정보를 응답으로 전달합니다.
어떤 리소스를 변화시키는지, 혹은 어떤 응답이 제공되는지에 따라 각기 다른 엔드 포인트를 사용하기 때문에, 적절한 엔드 포인트를 작성하는 것이 중요하죠. 엔드포인트는 리소스에 집중해 명사 형태의 단어로 작성하는 것이 바람직합니다.
더불어 요청에 따른 응답으로 리소스를 전달할 때도, 사용한 리소스에 대한 정보와 함께 리소스 사용에 대한 성공/실패 여부를 반환해야 합니다.
🚩2단계
CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것이 중요합니다.
URI에 행위가 포함되지 않고 대신 4가지의 HTTP 메서드를 사용해서 표현합니다. 현재 가장 많은 REST API는 이 단계에 해당한다고 해요.
예를 들어 조회(READ)하기 위해서는 GET 메서드를 사용하여 요청을 보냅니다. 이때 GET 메서드는 body를 가지지 않기 때문에 query parameter를 사용하여 필요한 리소스를 전달합니다.
생성(CREATE)하기 위해서는 POST 메서드를 사용하여 요청을 보내야 하며 POST 요청에 대한 응답이 어떻게 반환되는지가 중요합니다. 이 경우 응답은 새롭게 생성된 리소스를 보내주기 때문에, 응답 코드는 201 Created 로 명확하게 작성해야합니다. 또한 관련 리소스를 클라이언트가 Location 헤더에 작성된 URI를 통해 확인할 수 있도록 하면 REST 성숙도 모델의 2단계를 충족한 것이라고 볼 수 있습니다.
다음과 같은 4가지 종류의 HTTP 메서드에 대한 규칙들도 지켜주어야 합니다.
- GET 메서드 같은 경우는 서버의 데이터를 변화시키지 않는 요청에 사용해야 합니다.
- POST 메서드는 요청마다 새로운 리소스를 생성하고 PUT 메서드는 요청마다 같은 리소스를 반환합니다. 이렇게 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 합니다. 멱등성을 가지는 메서드 PUT과 그렇지 않은 메서드 POST는 구분하여 사용해야 합니다.
- PUT 메서드와 PATCH 메서드도 구분하여 사용해야 합니다. PUT은 교체, PATCH는 수정의 용도로 사용합니다.
여기까지 2단계였는데요. 모범적인 API 디자인조차도 REST 성숙도 모델의 3단계까지 적용한 경우는 드뭅니다. 그러니 2단계까지 적용하면 대체적으로는 잘 작성된 API라고 해도 좋을 것 같습니다.
🚩3단계
마지막 3단계는 HATEOAS라는 약어로 표현되는 하이퍼미디어 컨트롤을 적용합니다.
요청까지 2단계와 동일하지만, 응답에 리소스의 URI를 포함한 링크 요소를 삽입하여 작성해야 하는 것이죠. 이 새로운 링크들은 다양한 액션들을 위한 용도입니다. 이처럼 응답 내에 새로운 링크를 넣어 새로운 기능에 접근할 수 있도록 하는 것이 3단계의 핵심 포인트입니다.
바람직한 REST API 모범 사례 작성법
https://www.freecodecamp.org/korean/news/rest-api-mobeom-sarye-rest-endeupointeu-seolgye-yesi/
REST API 모범 사례 – REST 엔드포인트 설계 예시
웹 개발에서 REST API는 클라이언트와 서버 간 통신을 원활하게 하는 중요한 역할을 합니다. 여기서 클라이언트는 프론트엔드, 서버는 백엔드라고 생각할 수 있습니다. 클라이언트(프론트엔드)와
www.freecodecamp.org
🎈Open API
open API란 모두에게나 열려있는 API를 말합니다. 국가에서 제공하는 공공 데이터도 여기에 포함되겠죠. 다만 이것이 무제한으로 이용될 수 있다는 뜻은 아니며, 이용 수칙에 따라 각각 다른 제한 사항이 존재할 수 있으니 유의해야 합니다.
국내에서는 다음과 같이 정부가 open API를 제공하고 있습니다.
공공데이터 포털
국가에서 보유하고 있는 다양한 데이터를『공공데이터의 제공 및 이용 활성화에 관한 법률(제11956호)』에 따라 개방하여 국민들이 보다 쉽고 용이하게 공유•활용할 수 있도록 공공데이터(Datase
www.data.go.kr
또한 이런 API를 이용하기 위해서는 대개 🔑API Key가 필요한데요. 이 키가 없으면 자신을 증명할 수 없기 때문에 API를 사용할 수 없는 경우가 많습니다. 따라서 데이터를 요청할 때에는 API Key를 받아 함께 전달해야 합니다.
바람직한 REST API 디자인 가이드라인 및 가장 자주 쓰이는 네트워크 상태 코드들
https://blog.restcase.com/5-basic-rest-api-design-guidelines/
5 Basic REST API Design Guidelines
As soon as we start working on an API, design issues arise. Robust and strong design is a key factor for API success. A poorly designed API will indeed lead to misuse or – even worse – no use at all by its intended clients: application developers. Crea
blog.restcase.com
'CODE STATES 44' 카테고리의 다른 글
| Section 2 회고 (1) | 2023.04.10 |
|---|---|
| 26일차~30일차 스터디 (0) | 2023.03.30 |
| HTTP, 네트워크 기초에 대한 글 (0) | 2023.03.29 |
| React를 잘근잘근 씹으며 만드는 Twittler(트0터 짭...) (1) | 2023.03.27 |
| Ubuntu로 React 쓸 때 세이브 반영이 안 되는 문제 (0) | 2023.03.22 |
