웹 API 설계 : 놓치기 쉬운 핵심 - 소개

 

 

소개

 

 

웹 API는 정의상 HTTP를 사용합니다. 웹 API 초기에는, 사람들이 HTTP 위에서 CORBA나 DCOM 같은 이전 세대 분산 기술의 기능을 구현하려고 많은 시간과 노력을 들였습니다. 그 결과 SOAP와 WSDL 같은 기술이 등장했습니다. 경험상 이러한 기술들은 대부분의 웹 API에는 너무 복잡하고 무겁고 취약하다는 것이 드러났습니다. SOAP와 WSDL을 대체한 아이디어는 HTTP 위에 복잡한 기술을 추가하지 않고, HTTP를 더 직접적으로 사용할 수 있다는 것이었습니다. 대부분의 현대 웹 API는 SOAP나 WSDL API보다 훨씬 단순하지만, HTTP 위에 가볍게 구현된 원격 프로시저 호출의 기본 아이디어를 어느정도 유지하고 있습니다. 이러한 API들은 RESTful API라고 불리게 되었습니다. Apigee에서는 가능하면 추가 개념을 사용하지 않고 HTTP만을 사용하는 것을 권장합니다.

이유는 다음과 같습니다:
인터페이스를 설계할 때는 사용자 입장에서 생각해야 합니다. API 제공자로서 하나의 API 또는 소수의 API 그룹만 다룰 수 있겠지만, 사용자들은 여러분의 API 외에도 더 많은 API를 사용하고 있을 가능성이 큽니다. 이는 그들이 기본적인 HTTP 기술 및 표준에 대한 상당한 지식과 다른 API 경험을 바탕으로 여러분의 API에 접근한다는 것을 의미합니다. 그렇기 때문에 자체적인 규칙을 만드는 것보다는 표준과 기존 관례를 따르는 것이 큰 가치를 지닙니다. HTTP 규격은 지금까지 업계에서 만들어진 것 중 가장 잘 작성되고, 잘 설계되었으며, 보편적으로 수용된 표준 중 하나입니다. 여러분이 사용자들에게 더 나은 대안을 발명할 가능성은 낮습니다. 모든 사용자가 HTTP 표준에 대한 자세한 지식을 가지고 있지는 않겠지만, 표준 HTTP 메커니즘을 배우게 하는 것이 여러분이 새로 만든 대안을 가르치는 것보다 사용자와 여러분 모두에게 더 나은 투자입니다.

예를 들어, API에서 리소스를 생성하기 위해 POST를 사용한다면, HTTP 표준의 일부인 201 상태 코드와 함께 새로 생성된 리소스의 URL이 포함된 Location 헤더를 응답에 포함하세요. 두 명이 동시에 동일한 웹 리소스를 업데이트하지 않도록 확인해야 한다면, ETag와 If-Match 헤더를 사용하세요. 이것 역시 HTTP 표준입니다. 만약 API가 사용자에게 여러 형식으로 데이터를 요청할 수 있는 기능을 제공한다면, HTTP Accept 헤더를 사용하세요.

여러분의 API에 특정한 표준 메커니즘에 대한 대안을 제공하고 싶다면 그렇게 해도 좋습니다. 그러나 그것을 표준 메커니즘을 지원하는 것에 추가하는 방식으로 하고, 대체하지는 마세요. 이렇게 하면 웹의 작동 방식을 이해하고 다른 API 경험이 있는 사용자들이 여러분에게 감사할 것입니다.

이 책은 전 세계의 주요 API 팀들과 협력하여 개발한 설계 실천 모음입니다. 여러분의 피드백을 듣고 싶습니다—동의하든, 반대하든, 또는 추가로 공유할 웹 API 설계 모범 사례와 팁이 있든 환영합니다. Apigee 커뮤니티의 API Design 그룹은 웹 API 설계 애호가들이 모여 설계 실천을 공유하고 토론하는 장소입니다. 여러분도 함께해 주시면 좋겠습니다.

 

 

 

 

 

[출처]
APIGEE-WEB-API-DESIGN-THE-MISSING-LINK