혼란스러운 API를 만들지 마세요! 여기에 깔끔한 코드 가이드가 있습니다🚀

API와 RESTful API는 모든 프로그래머가 익혀야 할 기본 개념입니다. API를 설계할 때 시스템 간의 효율적이고 효과적인 상호작용을 보장하기 위해 충족해야 하는 몇 가지 기본 요구 사항이 있습니다.

만약 아직 API가 무엇인지 잘 모르거나 RESTful API 개념을 이해하지 못했다면, 5분만 시간을 내어 계속 읽어보세요. 저는 쉽고 직관적으로 모든 것을 설명할 것입니다.

❓ API란 무엇인가요?

간단한 예시로 설명해드리겠습니다:
2000년대 초, 온라인 티켓 구매가 등장하기 시작했지만 대부분의 사람들은 여전히 전화로 항공편을 문의했습니다. 처음에는 가까운 역에 전화를 걸어 가능한 항공편이나 기차 시간표를 물어봤습니다. 그 정보를 받은 후, 해당 역으로 가서 티켓을 구매했습니다.

• 기술의 빠른 발전과 스마트폰의 보급으로 다양한 여행 앱이 등장하게 되었고, 이제 누구나 이러한 앱을 통해 티켓을 구매하는 방법을 배우게 되었습니다.

• 이제 티켓을 구매하는 것이 훨씬 간편해졌습니다. 앱에 출발지와 목적지를 입력하면, 관련된 모든 기차와 항공편 옵션을 확인할 수 있습니다. 시간과 좌석의 가용성뿐만 아니라 항공사 정보, 예상 소요 시간 등 다양한 세부 정보가 명확하고 간결하게 제공됩니다. 이를 통해 특정한 요구에 맞는 구매를 손쉽게 할 수 있습니다.
  

• 연결은 정말 놀라운 것입니다. 현재의 삶에서 우리는 다양한 앱을 통해 쇼핑, 독서, 실시간 방송 등을 손쉽게 즐기며, 이전에 없던 방식으로 세계와 사람들과 연결되고 있습니다.

• 그렇다면 이것이 어떻게 가능한 걸까요? 무엇이 앱을 이렇게 편리하게 만들까요? 정보가 어떻게 A 지점에서 B 지점으로 이동하여 손끝 하나로 모든 것을 할 수 있게 되는 걸까요?

• 이 모든 것을 가능하게 하는 다리—인터넷 세계의 숨은 영웅—바로 API입니다. API의 전체 형식은 Application Programming Interface입니다. 간단히 말하면, 브랜드가 개발한 인터페이스로, 제3자가 추가 기능을 만들고 이를 자사의 제품에 통합할 수 있도록 합니다.

• 앞서 제공된 예시로 돌아가 보겠습니다:
  예전에는 항공편 정보를 알고 싶다면 메신저가 필요했습니다. 전화 응답자가 바로 이 메신저 역할을 했으며, 우리가 말하는 API였습니다. 응답자는 당신의 요청을 시스템에 전달했습니다. 예를 들어, 내일 뉴욕행 항공편을 요청하면, 응답자는 그 정보를 찾아서 다시 당신에게 전달했습니다.

  • 이제 비행기 티켓을 구매할 때는 예약 시스템과 상호작용만 하면 됩니다. 여기서 날짜, 도시, 클래스 선호도를 선택할 수 있습니다. 이 시스템은 여러 항공사 웹사이트에서 데이터를 모으며, 이 정보를 집합적으로 수집하는 방법은 항공사와 상호작용하는 API를 통해서입니다.
  • 우리는 이제 여행 앱을 사용할 수 있게 해주는 것이 바로 API라는 것을 이해하게 되며, 이 원리는 애플리케이션, 데이터, 장치 간의 모든 상호작용에 보편적으로 적용됩니다. 각 시스템은 자사의 API를 사용해 서로 연결을 구축합니다.

❓ RESTful API란 무엇인가요?

• 인터넷이 아직 대중화되지 않았고 모바일 장치가 널리 보급되지 않았던 초창기에는 API에 대한 수요가 상대적으로 적었습니다. 그 당시 웹 애플리케이션은 주로 서버 측에서 운영되었으며, 페이지 요청 수와 동시 사용자 수가 적어 데이터 처리와 전송을 위한 복잡한 프로토콜을 사용했습니다.

• 모바일 장치의 사용이 급증하면서, 이러한 장치에서 웹 애플리케이션에 접근할 필요성이 커졌습니다. 이 변화는 사용자 행동과 기대에 큰 변화를 가져왔으며, 클라이언트와 서버 간의 더 효율적인 통신 방식이 필요해졌습니다. 여기서 API의 역할이 중요해졌습니다. API는 모바일 장치가 웹 애플리케이션과 원활하게 상호작용할 수 있도록 해주는 다리 역할을 했습니다.

• 따라서 개발을 위한 간소화된 API 세트는 명확하게 구조화되고, 표준화되며, 이해하기 쉽고 확장 가능해야 합니다. 이러한 특성을 완벽하게 구현한 것이 바로 RESTful API 스타일로, 이 스타일은 개발자와 조직 사이에서 점차 인기를 얻고 있습니다.

REST

• REST(Representational State Transfer)는 엄격한 표준이라기보다는 디자인 스타일 및 소프트웨어 아키텍처 스타일입니다. REST는 네트워크 애플리케이션을 생성하는 데 필요한 디자인 원칙과 제약 조건을 제공합니다. REST의 목표는 웹의 특성, 특히 HTTP 프로토콜을 활용하여 확장 가능하고 효율적인 서비스를 만드는 것입니다.

RESTful

• "RESTful"이라는 용어는 REST 원칙을 따르는 API나 서비스를 설명하는 형용사로 사용됩니다. 예를 들어, RESTful API는 REST가 정의한 특성과 설계 제약을 따르는 API입니다. 이는 API가 REST 아키텍처를 모방하며 예측 가능하고 표준화된 상호작용 패턴을 제공하도록 보장합니다.

RESTful API

• 우리가 일반적으로 접하는 API는 보통 다음과 같습니다:
  
• 하지만 RESTful API는 보통 다음과 같습니다:
  

💡 여섯 가지 원칙

• Roy Fielding은 HTTP 프로토콜의 주요 설계자 중 한 명입니다. 그의 논문에서는 REST 아키텍처의 개념을 설명하고, 그것의 여섯 가지 제약 조건을 제시했습니다. 이 여섯 가지 원칙은 RESTful API를 구축하는 데 있어 중요한 지침이 되며, API의 기능성과 확장성에 기여합니다. 각 원칙을 자세히 살펴보겠습니다:
  

Uniform Interface

• 앞서 본 두 가지 예시처럼, API의 가장 직관적인 특징은 REST 아키텍처의 원칙을 따르는 것입니다. RESTful 서비스에서는 통합된 인터페이스가 매우 중요합니다. 클라이언트는 인터페이스 구현에만 집중하면 되며, 이는 API의 가독성을 높이고 사용자들이 API를 편리하게 사용할 수 있도록 합니다.

• RESTful API는 URL을 통해 리소스를 찾고, HTTP 메서드를 통해 리소스를 조작합니다. 리소스에 대한 작업에는 가져오기, 생성하기, 업데이트하기, 삭제하기가 포함되며, 이는 HTTP 프로토콜의 GET, POST, PUT, DELETE와 일치합니다.

  • GET: 리소스 정보를 가져옵니다.
  • POST: 새로운 리소스를 생성합니다.
  • PUT: 기존 리소스를 업데이트합니다.
  • DELETE: 기존 리소스를 삭제합니다.

• 완전하게 RESTful 원칙을 따르는 팀 내에서는 백엔드가 프론트엔드에 /users API만 알려주면, 프론트엔드는 다음과 같은 작업을 직관적으로 이해할 수 있습니다:

  • 모든 사용자 얻기: GET /users
  • 특정 사용자 조회: GET /users/{id}
  • 새로운 사용자 생성: POST /users
  • 기존 사용자 업데이트: PUT /users/{id}
  • 사용자 삭제: DELETE /users/{id}

API의 수가 증가하고 시스템이 점점 복잡해지면 RESTful 아키텍처의 장점이 더욱 두드러집니다. 시스템을 일련의 리소스에 집중하여 이해하면 이해도와 기억력을 돕는 데 유리합니다.

Client-Server

• 클라이언트와 서버는 독립적이며 서로 분리될 수 있습니다.
  클라이언트는 데이터 요청과 처리의 책임을 지고, 서버는 데이터를 - 저장하고 요청을 처리하는 책임을 집니다.
  이 두 구성 요소는 일련의 규칙을 통해 협력하여 클라이언트가 필요한 데이터를 효율적으로 가져올 수 있도록 합니다.

Statelessness

• 이 원칙은 각 요청이 독립적이며 이전 요청과 관계가 없다는 것을 의미합니다. 서버는 클라이언트에 대한 상태 정보를 유지하지 않으며, 각 요청은 이를 처리하는 데 필요한 모든 정보를 포함해야 합니다.
• 이 접근 방식의 장점은 각 요청이 단순해져 이해하고 처리하기 쉬워지며, 확장성과 유지보수성이 향상된다는 것입니다.
• 예를 들어, 웹사이트에 로그인하는 경우를 생각해 보세요. 로그인 인터페이스에서 사용자 이름과 비밀번호를 입력하고 API를 통해 토큰을 얻습니다. 그 이후 모든 요청은 이 토큰을 포함해야 하며, 시스템은 첫 번째 로그인 후 로그인 상태를 추적하지 않습니다.

Cacheability

• 클라이언트와 서버는 캐시 가능한 콘텐츠에 대해 협상할 수 있으며, 서버는 적절한 HTTP 상태 코드를 설정하여 특정 데이터를 클라이언트가 캐시할 수 있는지 여부를 알릴 수 있습니다.
• 예를 들어, HTTP 응답에 Cache-Control 헤더가 포함되어 데이터가 얼마나 오래 캐시될 수 있는지 클라이언트에 전달합니다. 이렇게 하면 데이터 전송 효율성이 증가하고, 네트워크 대역폭 사용이 줄어들며, 데이터 접근 속도가 빨라집니다. 캐시된 콘텐츠를 효과적으로 관리함으로써 애플리케이션은 더 빠른 응답 시간과 원활한 사용자 경험을 제공합니다.

Layered System

• 클라이언트는 요청이 얼마나 많은 중간 레이어를 통과하는지 걱정할 필요가 없습니다. 그들의 주요 초점은 요청의 결과여야 합니다. - - 잘 설계된 아키텍처는 여러 레이어로 나눠져 있으며, 각 레이어는 고유한 작업을 독립적으로 수행합니다. 이러한 계층적 접근 방식은 시스템을 더 쉽게 유지보수할 수 있게 만들며, 다양한 레이어의 독립적인 교체나 확장이 가능하게 합니다.

예를 들어, 데이터베이스 저장소 레이어는 아키텍처의 다른 레이어와 독립적으로 작동할 수 있습니다. 이러한 독립성 덕분에 개발자는 데이터베이스 레이어를 교체하거나 확장할 수 있으며, 다른 레이어의 작동에 영향을 미치지 않습니다. 이러한 모듈화는 개발 프로세스를 간소화하고 시스템의 전체적인 복원력과 확장성을 향상시킵니다.

Code on Demand

• 클라이언트는 요청이 얼마나 많은 중간 레이어를 통과하는지 걱정할 필요가 없습니다. 그들이 집중해야 할 것은 요청의 결과입니다.

• 시스템의 아키텍처는 여러 레이어로 나누어지며, 각 레이어는 자신의 작업을 독립적으로 완료하는 책임을 집니다. 이러한 계층 구조는 시스템을 더 쉽게 유지보수할 수 있게 하고, 다양한 레이어를 독립적으로 교체할 수 있도록 합니다.

• 예를 들어, 데이터 저장소 레이어는 다른 레이어와 독립적으로 작동할 수 있습니다. 이 레이어는 다른 레이어의 기능에 영향을 미치지 않고 교체하거나 확장할 수 있습니다. 이러한 모듈화는 애플리케이션 아키텍처 내에서 더 나은 유지보수성과 확장성을 촉진합니다.

🔥 RESTful API 디자인 가이드라인
RESTful API의 이론적 측면에 대해 논의했으니, 이제 실제적인 측면으로 넘어가겠습니다: 가장 간단한 RESTful 스타일 API는 어떻게 설계할 수 있을까요?

HTTP Methods
HTTP는 다양한 동사를 사용하여 서로 다른 작업을 나타내며, 각 HTTP 요청 메서드는 고유한 의미를 가집니다. 앞서 설명한 것처럼, RESTful API는 리소스에 대한 작업을 설명하기 위해 HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용해야 합니다.

Versioning
버전 관리는 기존 클라이언트 애플리케이션에 영향을 주지 않으면서 RESTful API를 업데이트하는 것입니다. 일반적인 버전 관리 방법에는 다음과 같은 것들이 있습니다:

• URL 방법: URL을 변경하여 다른 버전을 나타냅니다. 예: https://api.example.com/api/v1/resources와 https://api.example.com/api/v2/resources
• Accept 헤더: 요청 헤더의 Accept 필드를 사용하여 원하는 API 버전을 표시합니다.
• 요청 매개변수: 요청 매개변수를 통해 버전을 지정합니다. 예: https://api.example.com/resources?version=1과 https://api.example.com/resources?version=2

각기 다른 회사와 팀들이 API 설계 방식에 대해 다양한 접근을 할 수 있지만, 저는 버전 관리 방법을 가능한 한 간단하고 직관적으로 유지하는 것이 중요하다고 생각합니다. URL에 버전을 직접 넣는 방식은 직관적이고 명확하며, 개발자들이 이해하고 사용하기 쉽습니다.

URLs Clearly Identify Resources

• API는 리소스를 식별하는 데 간결하고 명확한 URL을 사용해야 하며, 다양한 HTTP 메서드를 사용하여 동일한 리소스에 대해 다양한 작업을 수행합니다.

• 이 디자인은 클라이언트가 추가 정보나 광범위한 문서 없이 필요한 리소스를 쉽게 찾을 수 있게 합니다. 명확한 URL은 클라이언트가 API와 효과적으로 상호작용할 수 있는 직관적인 방법을 제공합니다.

• 반면, 불규칙한 URL은 여러 형태로 나타날 수 있으며, 다양한 개발자들이 이를 어떻게 상호작용할지 이해하기 위해 문서를 살펴봐야 할 수 있습니다. 비구조적인 URL은 혼란을 초래하고 개발의 비효율성을 유발할 수 있습니다.

• 표준화된 RESTful 스타일을 URL에 적용하면 고정된 형식이 되어 가독성이 향상됩니다. 명확한 명사와 이에 해당하는 HTTP 동사를 사용함으로써, 개발자들은 리소스를 쉽게 조작할 수 있으며, API 작업 시 더 직관적인 경험을 제공합니다.

여기 작은 팁:
만약 적절한 URL을 만들기 어렵다면, GitHub Open API를 참조해 보세요. 그곳에는 잘 구조화되고 정리된 URL 디자인이 풍부하게 있습니다.

HTTP 상태 코드
HTTP 상태 코드는 RESTful API 설계에서 중요한 부분을 차지하며, API 요청의 상태를 나타내고 클라이언트에게 요청이 성공했는지, 데이터가 올바르게 처리되었는지 알리는 역할을 합니다. 자주 사용되는 HTTP 상태 코드는 다음과 같습니다:

• 200 OK: 요청이 성공적으로 처리되었고, 요청한 데이터가 반환되었습니다.
• 201 Created: 요청이 성공적으로 처리되었고, 새로운 리소스가 생성되었습니다.
• 204 No Content: 요청이 성공적으로 처리되었지만, 반환할 데이터가 없으며 작업이 완료되었음을 나타냅니다.
• 400 Bad Request: 요청이 잘못된 형식이거나 필수 매개변수가 누락되어 실패했습니다.
• 401 Unauthorized: 인증 문제나 권한 부족으로 요청이 실패했습니다.
• 403 Forbidden: 클라이언트가 리소스에 접근할 권한이 없어서 요청이 실패했습니다.
• 404 Not Found: 요청한 리소스가 존재하지 않아 요청이 실패했습니다.
• 500 Internal Server Error: 내부 서버 오류로 인해 요청이 실패했습니다.

이러한 상태 코드는 클라이언트가 요청의 결과를 이해하는 데 도움을 주며, 개발자가 오류와 성공 시나리오를 효과적으로 처리할 수 있도록 합니다.

통일된 반환 데이터 형식
RESTful API에서 자주 사용되는 반환 데이터 형식은 JSON과 XML입니다.

• JSON (JavaScript Object Notation): 현재 가장 인기 있는 데이터 형식으로, 간단하고 가벼운 성질을 가지고 있으며, 파싱이 용이합니다. 그 가독성 덕분에 웹 애플리케이션에서 서버와 클라이언트 간의 데이터 교환에 자주 사용됩니다.
• XML (eXtensible Markup Language): 또 다른 널리 사용되는 데이터 형식으로, 유연성과 다양한 데이터 타입을 지원합니다. XML은 복잡한 데이터 구조를 표현할 수 있으며, 문서 검증이나 더 설명적인 형식이 필요한 경우에 선호됩니다.

잘 구조화되고 미적인 API 문서화
어떤 프로젝트 개발에서도, 특히 프론트엔드와 백엔드의 분리 구현 시 API는 중요한 역할을 합니다. 그로 인해 API 문서를 최신 상태로 유지하고 포괄적으로 관리하는 것이 중요합니다. 그러나 많은 프로그래머들이 문서 작성이 번거롭다고 느끼며, 심지어 회사의 API 문서가 Word 문서로 작성된 경우를 보았습니다.

다행히도, API를 관리하고 문서화하는 데 특화된 도구들이 많이 있습니다. 각 개발자나 팀마다 선호하는 도구가 있을 수 있지만, 저는 Apidog라는 훌륭한 API 관리 도구를 추천하고 싶습니다. 이 도구는 몇 번의 클릭만으로 API 문서를 생성할 수 있습니다.

Apidog의 가장 큰 장점은 문서화 과정을 크게 단순화시킨다는 점입니다. 여러 작업을 수행할 필요 없이, 사용하기 쉬운 시각적 인터페이스를 통해 API를 추가하면 도구가 자동으로 문서를 생성해 줍니다.

🌟 최종 생각

• 요약하자면, RESTful 스타일의 API는 효과적이고 잘 구조화되어 있지만, 많은 인터넷 회사들은 API 설계 시 그 가이드라인을 엄격하게 따르지 않습니다. 이는 REST가 규칙보다는 스타일에 가깝기 때문입니다. RESTful API를 지나치게 이상적으로 구현하면 상당한 비용과 복잡성을 초래할 수 있습니다.

• RESTful API 사용을 고려하고 있다면, 그것이 비즈니스 요구에 부합하는지 확인해야 합니다. 예를 들어, 프로젝트가 복잡한 데이터 상호작용을 요구한다면, 해당 요구 사항을 더 잘 수용할 수 있는 다른 API 설계 방법론을 탐색해야 할 수도 있습니다.

• 따라서 API 설계 접근 방식을 선택할 때 비즈니스 요구를 철저히 고려하는 것이 중요합니다. 또한, RESTful API가 시스템 아키텍처와 기술 스택에 호환되는지 확인해야 합니다. 이러한 고려 사항들은 RESTful API의 적절한 활용을 보장하고, 궁극적으로 더 효율적이고 신뢰할 수 있는 API 성능을 이끌어낼 것입니다.

• 장기적으로 API 설계는 단순히 백엔드 팀의 책임으로만 여겨져서는 안 됩니다. 제품 디자인 과정에서 전체 제품 팀이 협력하는 공동 작업이어야 합니다. 잘-rounded한 접근 방식을 통해 API 사용의 모든 측면(사용성에서 기능성까지)을 고려할 수 있습니다.

• 이 API와 RESTful API에 대한 간단한 개요에서는 이러한 표준을 엄격하게 구현할 필요는 없지만, RESTful 가이드라인과 같은 참조를 가지는 것이 매우 유용하다는 점을 강조했습니다. 이러한 가이드라인은 API 설계 및 효율성을 크게 향상시킬 수 있는 필수적인 통찰력과 모범 사례를 제공합니다. 이 정보가 모든 이들의 API 개발과 구현 과정에 도움이 되기를 바랍니다.

📖 참고 자료
[1] GitHub Open API: https://docs.github.com/en/rest/actions/artifacts
[2] Apidog: https://apidog.com/