RESTFUL API 설계

REST API의 등장배경

 

멀티플랫폼의 등장

• 단순히 하나의 브라우저만 지원하면 되었던 이전과는 달리, 최근의 서버 프로그램은 여러 웹 브라우저는 물론이며, 아이폰, 안드로이드 애플리케이션과의 통신에 대응할 수 있어야 합니다. 

그전에는?

• 2010년 이전만 해도 Server Side에서 데이터를 전달해주는 Client 프로그램의 대상은 PC 브라우저로 그 대상이 명확했다.
• 클라이언트의 환경이 비교적 일정했기 때문에, 서버에서 완성된 웹 페이지를 만들어 전송하는 방식이 일반적이었습니다. 그렇다 보니 그냥 JSP ASP PHP 등을 필요한 웹페이지를 구성하고 작업을 진행하면 됐다.
• 즉, 데이터와 프레젠테이션 로직이 서버에서 함께 처리되었습니다.

 

그래서 범용적이고 유연하고 확장성이 있는 구조가 필요

• 서버는 데이터만을 제공하고, 클라이언트가 자신의 환경에 맞게 데이터를 표현하는 방식으로 변화했습니다.
• JSON이나 XML 같은 범용적인 데이터 형식을 사용하여 다양한 클라이언트와 호환성을 확보했습니다. 클라이언트와 서버의 역할이 명확히 분리되어, 각자의 영역에서 독립적으로 발전할 수 있게 되었습니다.

 

RESTFUL API란?

• API : 애플리케이션이나 서비스가 다른 애플리케이션이나 서비스 내의 리소스에 액세스할 수 있도록 일련의 정의, 프로토콜입니다. MSA API, Open API 등
•  REST 아키텍처의 제약 조건을 준수하는 애플리케이션 프로그래밍 인터페이스입니다
• REST (Representational State Transfer) : '자원의 표현에 의한 상태전달'이라는 설계원칙. 개발자들 사이에서 웹서버 구현가이드

REST의 구성

• 자원(Resource) - URL
• 행위(Verb) - Http Method
• 표현(Representations)

1. 자원 (Resource) URL

• 모든 자원에 고유한 ID가 존재하고, 이 자원은 Server에 존재한다.
• 자원을 구별하는 ID는 /orders/order_id/1 와 같은 HTTP URI 이다.

2. 행위 (Verb) - Http Method

• HTTP 프로토콜의 Method를 사용한다.
• HTTP 프로토콜은 GET, POST, PUT, DELETE와 같은 메서드를 제공한다.

3. 표현 (Representaion of Resource)

• Client가 자원의 상태 (정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답 (Representation)을 보낸다
• REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타낼 수 있다.
• 현재는 JSON으로 주고 받는 것이 대부분이다.

 

REST 원칙

무상태성 (Stateless)

• REST는 HTTP의 특성을 이용하기 떄문에 무상태성을 갖는다.

Representations

• Represntational State : Representation of data란 데이터베이스의 실제 데이터를 직접 전송하는 것이 아니라, 그 데이터를 특정 형식(예: JSON, XML)으로 변환하여 전송합니다.  client-server가 db에 종속적이지 않은 관계를 갖게됨.

Resource-Based

• In REST, everything is considered a resource, which can be identified using URIs (Uniform Resource Identifiers). Resources are manipulated using standard HTTP methods like GET, POST, PUT, and DELETE.

계층화 (Layered System)

• 클라이언트와 서버가 분리되어 있기 때문에 중간에 프록시 서버, 암호화 계층 등 중간매체를 사용할 수 있어 자유도가 높다

유니폼 인터페이스 (Uniform)

• Uniform Interface는 Http 표준에만 따른다면 모든 플랫폼에서 사용이 가능하며, URI로 지정한 리소스에 대한 조작을 가능하게 하는 아키텍쳐 스타일을 말한다. URI로 지정한 Resource에 대한 조작을 통일되고 한정적인 인터페이스로 수행한다.
• 즉, 특정 언어나 기술에 종속되지 않는다.

 

RESTful API 개발 원칙

a. 자원을 식별할 수 있어야 한다.

• URL (Uniform Resource Locator) 만으로 내가 어떤 자원을 제어하려고 하는지 알 수 있어야 한다. 자원을 제어하기 위해서, 자원의 위치는 물론 자원의 종류까지 알 수 있어야 한다는 의미이다.
• Server가 제공하는 정보는 JSON 이나 XML 형태로 HTTP body에 포함되어 전송 시킨다.

b. 자기 서술적이어야 한다.

• 데이터에 대한 메타정보만 가지고도 어떤 종류의 데이터인지, 데이터를 위해서 어떤 어플리케이션을 실행 해야 하는지를 알 수 있어야 한다.
• 즉, 데이터 처리를 위한 정보를 얻기 위해서, 데이터 원본을 읽어야 한다면 자기 서술적이지 못하다

 

유의사항

• 이 REST API를 개발하다보면 HTTP의 Response 규약을 지키지 않고 본인들이 만들어넨 JSON 컨벤션으로 응답하는 경우를 많이 확인 할 수 있는데 그것은 옳지 않은 개발 방향이다.
• 왜냐하면 Client Side가 정형화 되어있지 않은 환경에서 개발 속도를 저하하는 가장 큰 이유는 표준을 지키지 않았기 때문이다.

 

c. 그 외 REST API URL 명명법 내용참고

https://restfulapi.net/resource-naming/

• URI는 자원의 주소에 대한 표현이기때문에 폴더와 같이 계층구조를 유지한다.
• 동사를 사용해서는 안된다. 특히, CRUD는 명명에 쓰지 않는다. CRUD는 Method에 포함되어있어야하기 때문이다.
  • /device/manage(x) device/managed-device (o)
  • /script/{id}/execute (x) /script/{id}/status(o) ( Post method로 action=execute 데이터를 삽입 )
  • /sign-in, /sign-up 같은 특수 url은 예외로 허용한다
• Collection과 single을 구분하여 표기한다.

 

REST API 설계방식 기타

• API작성은 화면중심이 아니라 엔티티 중심으로 작성한다. 이는, 화면은 언제든지 변경될 수 있으나 ERD는 변경되지 않기때문에 화면종속적인 설계는 피한다.
• query param은 필터링이나 검색 조건을 전달할 때 적합, pathvariable은 리소스를 식별하기 위해 경로의 일부로 값을 전달할 때 사용됩니다. 그러므로 단건 조회는 pathvariable로 하고 다건 조회는 queryparam으로 한다. 왜냐면 pathvariable은 변수가 두개이상이 들어가는 것이 restful api에 적합하기 때문이다.
• MSA 방식에서 서비스간 연관관계가 없다면 서비스 단위로 Path를 별도로 분리하는 것이 좋다. 

 

https://velog.io/@somday/RESTful-API-%EC%9D%B4%EB%9E%80

https://www.ibm.com/kr-ko/topics/rest-apis

https://www.redhat.com/ko/topics/api/what-is-a-rest-api

그래서 요약하자면 ?

RESTful API는 플랫폼 독립적으로 설계되며, 1. 계층 구조를 갖춘 자원을 URI로 식별하고,2. HTTP 메소드를 통해 행위를 정의하며,3,  독립적인 데이터 표현을 사용한 자기서술적인 HTTP API입니다

 

 

RESTful API 응답설계

 

To make your API truly RESTful, use the most appropriate status code for each situation.

Scenario	Method	Recommended HTTP Status	CodeDescription
✅ Success: Return Data	GET	200 OK	Request succeeded, and data is returned.
✅ Success: Resource Created	POST	201 Created	Resource was successfully created.
✅ Success: No Content	DELETE / PATCH / PUT	204 No Content	Action was successful, but no response body is needed.
⚠️ Client Error: Invalid Request	POST / PUT	400 Bad Request	The request is invalid or missing required data.
🚫 Unauthorized Request	ANY	401 Unauthorized	Authentication is required.
⛔ Forbidden Action	ANY	403 Forbidden	Client is authenticated but lacks permission.
❌ Resource Not Found	GET	404 Not Found	The requested resource does not exist.
🔄 Resource Conflict	POST / PUT	409 Conflict	Request conflicts with existing data.
⏳ Too Many Requests	ANY	429 Too Many Requests	Client is making too many requests.
🛑 Server Error	ANY	500 Internal Server Error	An unexpected error occurred on the server.