RESTful API 설계 가이드 질문 1

RESTful API 설계 가이드에 질문 댓글이 달렸는데, 간단하게 답변하기보단 좀 자세히 답변해주고 싶어 글로 작성했습니다.

1. 예제에 good, bad 가 있는데 bad 는 사용하지 말라는 건지 아니면 사용해도 되는데 안 좋은 예라고 말하는 건지 알 수가 없네요.
2. 설계 가이드라고 나와 있는데 아직도 Rest api 가 완성된 형식이 없는 건지 아님 별도의 문법이 있어 각자의 서버에서 나름대로 사용자 정의가 가능한지요.
3. 서버는 웹서버에서 바로 구축이 가능한지 아니면 따로 서버를 구축해야 되는지 구축하려면 어떻게 구성하는지 ㅠㅠ

아래 모든 답변은 필자의 개인적인 생각입니다. 잘못된 부분이 있으면 언제든 댓글로 지적해주세요.

1. 예제에 good, bad 가 있는데 bad 는 사용하지 말라는 건지 아니면 사용해도 되는데 안 좋은 예라고 말하는 건지 알 수가 없네요.

TLDR; 사용하지 말라는 뜻입니다.

또한, 이미 저렇게 설계된 API가 있다면 최선을 다해 변경하라는 뜻입니다.

다만, 9. Versioning의 내용들은 필자의 주관이 많이 반영된 규칙이기 때문에 다르게 생각할 수 있습니다.

2. URL Rules, 5. Use HTTP status 내용들은 Good 예제를 따라주세요.

2. 설계 가이드라고 나와 있는데 아직도 Rest api 가 완성된 형식이 없는 건지 아님 별도의 문법이 있어 각자의 서버에서 나름대로 사용자 정의가 가능한지요.

TLDR: REST는 표준을 정하고 관리하지 않습니다. REST의 개념과 원리는 정해져 있지만, 이것들 통해 구현할 때 구체적인 공식 가이드는 없습니다. 별도의 문법은 없고 각자 API 환경에 맞게 정의한 가이드를 따르면 됩니다.

따라서, 어떤 API가 REST 하다고 딱 정해주진 못합니다. 코드가 잘못되면 알려주는 컴파일러처럼 REST에 문법이 있어 이것을 체크할 수 있는 것이 아닙니다.

그래서 작성한 글이 RESTful API 설계 가이드입니다. 추상적인 REST에 대한 개념을 예로 들면서 이렇게 하라고 작성한 지침입니다.

제목을 보면 REST API 설계 가이드가 아니고 RESTful API 설계 가이드입니다.
RESTful이란 REST 원리를 따르는 시스템을 지칭하는 용어입니다.

RESTful 한 API를 설계하고 싶다면, 아래 링크들을 참고해서 설계하면 됩니다.

• https://restfulapi.net/
• RESTful API 설계 가이드
• REST API 관점에서 바라보는 HTTP 상태 코드(HTTP status code)

추가적으로 API에 대한 이야기를 좀 하겠습니다. 아주 오래전(필자도 경험해보지 못한) 웹 개발은 단순했습니다.
클라이언트-서버 구조로 보통 클라이언트는 브라우저, 서버는 웹 애플리케이션 서버(JSP, PHP)로 HTTP를 통해 정보를 주고받았습니다.

그렇기 때문에 HTTP 말고 보편적이고 일관적인 규약은 필요 없었습니다. (클라이언트-서버 모두 하나의 조직에서 개발/사용하기 때문에)

그러나, 브라우저 위주의 클라이언트 환경에서 벗어나 모바일, IoT 등 매우 다양한 클라이언트들이 생겨났습니다.
이러한 클라이언트들이 생겨날 때마다 그 인터페이스에 맞는 서버 환경을 구축하기란 매우 어렵습니다.

그래서 생겨난 것이 API입니다.
어떤 클라이언트들이든 상관없이 HTTP를 사용할 수 있다면 서버의 자원을 제어할 수 있는 인터페이스를 만든 겁니다.

하지만, HTTP는 클라이언트/서버 간 정보를 주고받는 방법에 대한 비교적 간단한 프로토콜입니다.
통신 자체는 HTTP를 이용하면 되지만, API 설계(design)에 대한 내용은 없습니다. HTTP가 만들어질 당시엔 API에 대한 고려가 필요하지 않았기 때문입니다.

네트워크(HTTP를 사용하는 API 환경) 환경을 보편적이고 일관적으로 만들기 위해 만들어진 네트워크 아키텍처 원리가 REST입니다.

---

HTTP, REST처럼 계속 규약을 만들고 지키는 것은 생존과 관계있습니다.
관리되지 않는 코드와 시스템은 레거시 시스템이 될 가능성이 높고 이 시스템은 언젠가 없어지게 됩니다.

예를 들어, Five Clues That Your API isn't RESTful로 익숙한 All requests are POSTs처럼 모든 요청을 POST로 처리하게 만들었다고 가정합니다.
혼자 이렇게 개발하고 사용한다면 문제 될 게 없습니다. 하지만, 이 API의 기능 추가를 다른 사람이 진행하거나 API가 공개되어 불특정 다수가 사용하게 된다면 사용하기 불편한 API가 될 것이고 점차 사용되지 않는 API가 될 것입니다.

사용되지 않는 코드, 시스템, 서비스는 사라집니다.

3. 서버는 웹서버에서 바로 구축이 가능한지 아니면 따로 서버를 구축해야 되는지 구축하려면 어떻게 구성하는지 ㅠㅠ

TLDR; 질문의 요를 정확히 파악하지 못했습니다.

아래 두 상황을 비교하는 거 같은데 일단 제가 이해한 내용으로 설명하겠습니다.

• 서버는 웹서버에서 바로 구축이 가능한지
• 따로 서버를 구축해야 되는지

질문자님의 상황을 예상하면, 리눅스 서버(AWS EC2)에 웹 서버인 NGINX를 설치하고 PHP로 웹 프로젝트를 구축했습니다.
그런데, REST API가 필요하여 Express.js로 구축하기로 결정했습니다.
이때 Express.js가 설치되는 서버를 웹서버가 설치된 EC2에 같이 둘 건지 아니면 EC2를 하나 더 만들어서 API 서버로 사용할지를 물어보는 거 같습니다.

두 가지 모두 가능하지만, 일단 하나의 EC2에서 웹 서비스와 API 서버를 같이 운영해보고 나중에 다른 리눅스 서버에서 운영해보는 것을 추천합니다.

출처: https://www.journaldev.com/27234/nginx-reverse-proxy-node-angular

[NGINX] NGINX를 nodejs express의 reverse proxy로 사용하기

• 서버: 리눅스, 윈도우만 설치된 컴퓨터. AWS EC2
• 웹 서버: Apache, NGINX.
• 웹 애플리케이션 프레임워크: Java Spring, Python django, Node.js Express.js