훌륭한 웹 API 디자인을 위한 5가지 황금률
게시 됨: 2022-03-11"그들이 무슨 생각을 하고 있었나?" API를 통해 웹 서비스를 통합할 때? 그렇지 않다면 당신은 나보다 훨씬 운이 좋았습니다.
모든 소프트웨어 개발자는 프로젝트를 스파게티 코드로 전환하는 것이 얼마나 쉬운지 알고 있으며 웹 API는 웹이 엉키게 만드는 경향이 있습니다. 하지만 그렇게 할 필요는 없습니다. 사실 사람들이 실제로 즐겨 사용하고 생성하는 것도 즐길 수 있는 훌륭한 웹 API를 디자인하는 것이 가능합니다. 하지만 어떻게? 그 질문에 대한 답은 이 포스트의 내용입니다.
관점
솔루션을 구축할 때 대부분의 경우 프로그래머가 아니거나 일반적으로 기술적으로 정교하지 않은 최종 사용자를 위해 설계합니다. 당신은 그들에게 그래픽 인터페이스를 제공하고 있고, 당신이 일을 제대로 했다면 그들이 하기 위해 인터페이스가 필요한 것에 대해 그들로부터 꽤 좋은 아이디어를 얻은 것입니다.
하지만 API 개발은 다릅니다. 당신은 프로그래머 를 위한 인터페이스를 디자인하고 있습니다. 아마도 그들이 누구인지도 모르는 상태일 것입니다. 그리고 그들이 누구이든 간에 소프트웨어의 모든 작은 결함을 지적할 수 있는 기술적 정교함(또는 최소한 기술적 정교함을 가지고 있다고 생각할 것)이 있을 것입니다. 귀하의 사용자는 귀하가 자신의 API에 대해 중요하게 생각하는 만큼 API에 대해 비판적일 가능성이 높으며, 이를 매우 좋아할 것입니다.
그런데 거기에 아이러니의 일부가 있습니다. 누구나 사용하기 쉬운 웹 API를 만드는 방법을 이해해야 한다면 바로 당신 입니다. 결국, 당신은 API 사용자와 같은 소프트웨어 엔지니어이므로 그들의 관점을 공유합니다. 안 그래?
글쎄, 당신은 확실히 그들의 관점을 이해 하지만, 당신은 반드시 그들의 관점을 공유 하지 않습니다. API를 개발하거나 향상 시킬 때 API 디자이너 의 관점이 있는 반면 API 사용자 의 관점이 있습니다.
API 디자이너 는 일반적으로 "이 서비스에서 수행해야 하는 작업은 무엇입니까?" 와 같은 질문에 중점을 둡니다. 또는 "이 서비스는 무엇을 제공해야 합니까?" , API 사용자 는 "이 API를 사용하여 필요한 작업을 수행하는 방법" 에 중점을 둡니다. , 또는 더 정확하게는 "이 API에서 필요한 것을 얻기 위해 최소한의 노력을 기울이려면 어떻게 해야 합니까?" .
이러한 서로 다른 질문은 두 가지 매우 다른 관점으로 이어집니다. 결과적으로 훌륭한 API를 설계하기 위한 필수 전제 조건은 API 디자이너의 관점에서 API 사용자의 관점으로 관점을 전환하는 것입니다. 다시 말해서, 당신이 자신의 사용자라면 자연스럽게 묻게 될 질문을 계속해서 스스로에게 물어보세요. API 가 무엇을 할 수 있는지 생각하기보다 API가 필요하거나 사용 되기를 원하는 다양한 방법에 대해 생각한 다음 API 사용자가 해당 작업을 가능한 한 쉽게 하는 데 집중하십시오.
이것이 쉽고 명백하게 들릴지 모르지만 API가 이러한 방식으로 디자인되는 경우가 얼마나 드문지 놀랍습니다. 경력에서 만난 API에 대해 생각해 보십시오. 얼마나 자주 이러한 관점을 염두에 두고 설계된 것처럼 보입니까? 웹 API 디자인은 어려울 수 있습니다.
따라서 다음과 같이 훌륭한 웹 API 설계를 위한 5가지 황금 규칙에 대해 이야기해 보겠습니다.
- 선적 서류 비치
- 안정성과 일관성
- 유연성
- 보안
- 채택 용이성
규칙 1: 문서화
선적 서류 비치. 네, 여기서 시작하겠습니다.
당신은 문서를 싫어합니까? 글쎄, 나는 공감할 수 있지만 "사용자 관점" 모자를 쓰고 문서를 작성해야 하는 것보다 더 싫은 것은 문서화되지 않은 API를 사용하려고 시도해야 한다는 것입니다. 난 내 경우를 휴식.
결론은 누구든지 API를 사용하려면 문서화가 필수적이라는 것입니다. 이 문제를 해결하기만 하면 됩니다. 사용자가 가장 먼저 보게 되는 것이므로 어떤 면에서는 선물 포장과도 같습니다. 프레젠테이션을 잘 하면 사람들이 API를 사용하고 특이한 점을 참을 가능성이 높아집니다.
그렇다면 좋은 문서를 작성하려면 어떻게 해야 할까요?
비교적 쉬운 부분은 API 메소드 자체를 문서화하는 것입니다. 즉, 예제 요청 및 응답과 함께 두 요소의 각 요소에 대한 설명입니다. 다행스럽게도 문서 생성 작업을 용이하게 하고 단순화하는 소프트웨어 도구의 수가 증가하고 있습니다. 또는 API, 엔드포인트 및 함수를 자체 검사하고 해당 문서를 생성하는 무언가를 직접 작성할 수 있습니다.
그러나 훌륭한 문서와 적절한 문서를 구분하는 것은 사용 예제와 이상적으로는 자습서가 포함되어 있다는 것입니다. 이것은 사용자가 API와 시작 위치를 이해하는 데 도움이 됩니다. 그것은 그들을 지향하고 그들의 두뇌에 당신의 API를 로드하는 데 도움이 됩니다.
예를 들어, Twilio 개발자가 API에 대한 모든 클래스, 모든 메서드 및 가능한 모든 응답을 나열해야 하지만 SMS를 보내거나 통화를 추적하거나 API 사용자가 해당 정보를 찾고 응집력 있게 이해하려면 정말 오랜 시간이 걸립니다. 이름 외에 어떤 용도로 사용되었는지에 대한 통찰력 없이 클래스와 메서드의 거대한 트리를 정렬하는 것을 상상할 수 있습니까? 끔찍하지 않나요? 그러나 이것이 바로 많은 API 제공자가 하는 일이므로 API를 자신 외에는 누구에게나 불투명하게 남겨둡니다. Rackspace CloudFiles 개발자 및 API 가이드가 그러한 예입니다. 그들이하고있는 일과 제공하는 것을 이미 이해하지 않는 한 방향을 잡기가 어렵습니다.
따라서 개발자가 수행하려는 작업의 골격을 포함하여 개발자를 빠르게 시작하고 실행하는 데 도움이 되는 간결한 자습서를 작성한 다음 확장할 수 있도록 보다 상세하고 완전히 문서화된 기능 목록의 방향을 알려줍니다. 그들이 가진 것에.
문서 작성을 마치면 문서가 자신이 아닌 다른 사람에게도 의미가 있는지 확인하십시오. 당신의 네트워크에 있는 다른 개발자들에게 그것을 보내고, 그들에게 설명서를 가리키는 것 외에는 지시를 내리지 말고, 그들에게 약 15분 안에 튜토리얼을 따르거나 정말 기본적인 것을 만들도록 요청하십시오. 15분 안에 API와 기본 통합을 할 수 없다면 해야 할 일이 더 많습니다.
훌륭하고 상세한 문서의 주목할만한 예는 Twilio, Django 및 MailChimp를 확인하십시오. 이러한 제품 중 어느 것도 반드시 해당 시장에서 최고가 될 수는 없지만(모두 좋은 제품이지만), 시장 내에서 최고의 문서를 제공하여 테마를 구별합니다.
규칙 2: 안정성과 일관성
Facebook의 API를 사용해 본 적이 있다면 Facebook이 API를 얼마나 자주 사용하지 않고 완전히 다시 작성하는지 알 것입니다. 당신이 그들의 해커 문화나 그들의 제품을 아무리 존중한다 해도 그들의 관점은 개발자 친화적이지 않습니다. 그들이 여전히 성공하는 이유는 API가 훌륭하기 때문이 아니라 10억 명의 사용자가 있기 때문입니다.
그러나 그러한 엄청난 사용자 기반과 시장 점유율의 사치를 누리지 못할 것입니다. 따라서 상당히 오랜 기간 동안 이전 버전을 실행하고 지원하는 훨씬 덜 휘발성인 API가 필요할 것입니다. 어쩌면 몇 년. 이를 위해 몇 가지 팁과 요령을 소개합니다.
예를 들어 API가 URL http://myapisite.com/api/widgets 를 통해 액세스할 수 있고 JSON 형식으로 응답을 제공한다고 가정해 보겠습니다. 언뜻 보기에는 괜찮아 보이지만 JSON 응답의 형식을 수정해야 하는 경우 어떻게 됩니까? 이미 당신과 통합된 모든 사람들은 무너질 것입니다. 죄송합니다.
따라서 미리 계획을 세우고 처음부터 API 버전을 지정하고 버전 번호를 URL에 명시적으로 통합합니다(예: http://myapisite.com/api/widgets?version=1 또는 http://myapisite.com/api/widgets/v1 ) 버전 1이 작동하는 것에 의존할 수 있고 준비가 되면 모든 후속 버전으로 업그레이드할 수 있습니다. 특정 시점에서 이전 버전을 단계적으로 제거해야 하는 경우 계속 진행하되 충분한 공지를 하고 일종의 전환 계획을 제공하십시오.
좋은 URL 체계는 URL에 주요 버전을 포함합니다. 출력 형식이나 지원되는 데이터 유형을 변경하면 새 주 버전으로 충돌해야 합니다. 일반적으로 출력에 키나 노드를 추가하는 것이 전부인 경우 동일한 버전을 유지하는 것이 허용되지만 안전을 위해 출력이 변경될 때마다 버전을 충돌시킵니다.
API는 시간이 지남에 따라 안정적일 뿐만 아니라 내부적으로 일관성이 있어야 합니다. 사용 중인 엔드포인트에 따라 데이터 POST의 매개변수 이름이나 메서드를 변경하는 많은 API를 보았습니다. 대신 API 내에서 공통 매개변수를 전역적으로 처리하고 상속 또는 공유 아키텍처를 사용하여 API 전체에서 일관되게 동일한 명명 규칙 및 데이터 처리를 재사용해야 합니다.
마지막으로 사용자가 업그레이드 방법을 정확히 알 수 있도록 API 버전 간의 차이점을 표시하기 위해 변경 로그를 기록하고 게시해야 합니다.
규칙 3: 유연성
GIGO(가비지 인, 가비지 아웃)는 대부분의 프로그래머에게 잘 알려진 주문입니다. 웹 API 디자인에 적용되는 이 기본 원칙은 요청 유효성 검사에 대해 상당히 엄격한 접근 방식을 지시하는 경향이 있습니다. 정말 좋은데요? 혼란, 문제 없습니다.
그러나 모든 것이 그렇듯이 균형이 필요합니다. 사용자가 귀하의 서비스를 사용하기를 원하는 모든 방식을 예상할 수는 없고 모든 클라이언트 플랫폼이 일관되지 않기 때문에(즉, 모든 플랫폼이 JSON 지원이 매우 좋거나 적절한 OAuth 라이브러리 등을 갖고 있지는 않음) 다음을 수행하는 것이 좋습니다. 입력 및 출력 제약 조건과 관련하여 적어도 어느 정도의 유연성 또는 허용 오차를 갖습니다.
예를 들어, 많은 API는 JSON, YAML, XML 등과 같은 다양한 출력 형식을 지원합니다. al.이지만 URL 자체의 형식 지정만 지원합니다. 유연성을 유지하기 위해 URL(예: /api/v1/widgets.json )에 이를 지정하도록 허용하거나 Accept: application/json HTTP 헤더를 읽고 인식하거나 다음을 지원할 수도 있습니다. ?format=JSON 등과 같은 쿼리 문자열 변수.
그리고 우리가 거기에 있는 동안 지정된 형식이 대소문자를 구분하지 않도록 하여 사용자가 ?format=json 도 지정할 수 있도록 하지 않는 이유는 무엇입니까? 이는 API 사용자의 불필요한 불만을 완화하는 방법의 전형적인 예입니다.
또 다른 예는 변수를 입력하는 다양한 방법을 허용하는 것입니다. 따라서 다양한 출력 형식이 있는 것처럼 다양한 입력 형식(예: 일반 POST 변수, JSON, XML 등)도 허용합니다. 최소한 표준 POST 변수를 지원해야 하며 많은 최신 애플리케이션도 JSON을 지원하므로 이 두 가지를 시작하는 것이 좋습니다.
여기서 요점은 모든 사람이 귀하의 기술적인 선호도를 공유한다고 가정해서는 안 된다는 것입니다. 다른 API가 작동하는 방식에 대한 약간의 연구와 다른 개발자와의 대화를 통해 유용하고 API에 포함할 수 있는 다른 유용한 대안을 얻을 수 있습니다.
규칙 4: 보안
보안은 분명히 웹 서비스에 구축하는 가장 중요한 것 중 하나이지만 너무 많은 개발자가 이를 사용하기 어렵게 만듭니다. API 제공자는 API에 액세스할 때 인증 및 권한 부여 방법에 대한 유용한 예를 제공해야 합니다. 이것은 최종 사용자가 작업하는 데 몇 시간을 소비하는 어려운 문제가 아니어야 합니다. 코드를 작성할 필요가 없도록 하거나 작성하는 데 5분 미만이 소요되도록 하십시오.
대부분의 API에서 저는 토큰이 사용자에게 할당된 임의의 해시이고 도난당한 경우 언제든지 재설정할 수 있는 간단한 토큰 기반 인증을 선호합니다. 토큰이 POST 또는 HTTP 헤더를 통해 전달되도록 허용합니다. 예를 들어, 사용자는 SHA-1 토큰을 POST 변수로 보내거나 "Authorization: da39a3ee5e6b4b0d3255bfef95601890afd80709"와 같은 형식의 헤더로 보낼 수 있습니다.
또한 짧은 숫자 식별자가 아닌 보안 토큰을 선택하십시오. 돌이킬 수 없는 것이 가장 좋습니다. 예를 들어, 사용자 생성 중에 SHA 토큰을 생성하고 데이터베이스에 저장하는 것은 비교적 간단합니다. 그런 다음 해당 토큰과 일치하는 모든 사용자에 대해 데이터베이스를 간단히 쿼리할 수 있습니다. SHA(User.ID + "abcd123") 와 같은 고유 식별자와 솔트 값으로 생성된 토큰을 수행한 다음 일치하는 사용자를 쿼리할 수도 있습니다. 예: where TokenFromPost = SHA(User.ID + "abcd123") 입니다.
또 다른 아주 좋은 옵션은 OAuth 2 + SSL입니다. 어쨌든 SSL을 사용해야 하지만 OAuth 2는 서버 측에서 구현하기가 상당히 간단하고 많은 공통 프로그래밍 언어에 대해 라이브러리를 사용할 수 있습니다.
당신이 만든 API가 자바스크립트를 통해 공개 웹사이트에서 접근 가능해야 한다면, 당신은 또한 토큰에 대한 계정당 URL 목록의 유효성도 확인해야 합니다. 그렇게 하면 아무도 API 호출을 검사하고 사용자의 토큰을 훔쳐 스스로 사용할 수 없습니다.
다음은 염두에 두어야 할 몇 가지 중요한 사항입니다.
화이트리스트 기능. API를 사용하면 일반적으로 데이터에 대한 기본적인 생성, 읽기, 업데이트 및 삭제 작업을 수행할 수 있습니다. 그러나 모든 엔터티에 대해 이러한 작업을 허용하고 싶지 않으므로 각 엔터티에 허용 가능한 작업의 화이트리스트가 있는지 확인하십시오. 예를 들어 승인된 사용자만
/user/delete/<id>와 같은 명령을 실행할 수 있는지 확인하십시오. 마찬가지로, 사용자의 요청으로 전송된 모든 유용한 헤더도 화이트리스트에 대해 유효성을 검사해야 합니다. Content-type 헤더를 허용하는 경우 사용자가 보내는 모든 것이 실제로 지원되는 콘텐츠 유형의 whilelist와 일치하는지 확인하십시오. 그렇지 않은 경우 406 Not Acceptable 응답과 같은 오류 메시지를 다시 보냅니다. 많은 API가 자동으로 생성되거나 대신 블랙리스트를 사용하므로 화이트리스트에 추가하는 것이 중요 합니다 . 그러나 보안의 황금률은 아무 것도 없이 시작하고 원하는 것만 명시적으로 허용하는 것 입니다.CSRF(교차 사이트 요청 위조)로부터 자신을 보호하십시오. 세션 또는 쿠키 인증을 허용하는 경우 CSRF 공격으로부터 자신을 보호하고 있는지 확인해야 합니다. OWASP(Open Web Application Security Project)는 이러한 취약점을 방지하는 방법에 대한 유용한 지침을 제공합니다.
리소스에 대한 액세스를 확인합니다. 모든 요청에서 사용자가 참조하는 특정 항목에 실제로 액세스할 수 있는지 확인해야 합니다. 따라서 사용자의 신용 카드 세부 정보를 볼 수 있는 끝점이 있는 경우(예:
/account/card/view/152423) ID "152423"이 사용자가 실제로 액세스할 수 있는 리소스를 참조하는지 확인하십시오.모든 입력을 확인합니다. 사용자의 모든 입력은 안전하게 구문 분석되어야 하며, XML 또는 JSON과 같은 복잡한 입력을 사용하는 경우 잘 알려진 라이브러리를 사용하는 것이 좋습니다. 자신의 파서를 만들지 마십시오. 그렇지 않으면 상처의 세계에 빠지게 됩니다.
규칙 5: 채택 용이성
이것은 실제로 무리에서 가장 중요한 규칙이며 다른 모든 규칙을 기반으로 합니다. 문서화 규칙에서 언급했듯이 API를 처음 접하는 사람들에게 이것을 시도하십시오. 튜토리얼을 따랐더라도 몇 분 안에 최소한 API의 기본 구현을 시작하고 실행할 수 있는지 확인하십시오. 저는 15분이 좋은 목표라고 생각합니다.
다음은 API 채택을 용이하고 용이하게 하기 위한 몇 가지 구체적인 권장 사항입니다.
사람들이 실제로 API를 사용할 수 있고 매번 처음으로 작동하는지 확인하세요. 새로운 사람들이 때때로 API를 구현하여 여러분이 면역이 된 어떤 방식으로든 혼동되지 않는지 확인하도록 하십시오.
간단하게 유지하세요. 멋진 인증을 하지 마십시오. 미친 사용자 정의 URL 구성표를 수행하지 마십시오. SOAP, JSON, REST 등을 재발명하지 마십시오. 개발자가 API + 10 불분명한 신기술이 아닌 API만 배우도록 이미 구현되어 있고 널리 인정되는 모든 도구를 사용하십시오.
서비스와 인터페이스할 언어별 라이브러리를 제공합니다. Alpaca 또는 Apache Thrift와 같이 라이브러리를 자동으로 생성하는 몇 가지 유용한 도구가 있습니다. 현재 Alpaca는 Node, PHP, Python 및 Ruby를 지원합니다. Thrift는 C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi 등을 지원합니다.
필요한 모든 가입을 간소화합니다. 오픈 소스 API를 개발 중이 아니거나 어떤 종류의 등록 프로세스가 있는 경우 등록 시 사용자가 매우 빠르게 튜토리얼로 안내되는지 확인하십시오. 또한 사람이 개입할 필요 없이 등록 프로세스를 완전히 자동화할 수 있습니다.
우수한 지원을 제공합니다. 채택의 큰 장벽은 지원 부족입니다. 버그 보고서를 어떻게 처리하고 대응할 것입니까? 불분명한 문서는 어떻습니까? 순박한 사용자? 포럼, 버그 추적기 및 이메일 지원은 환상적인 시작이지만 누군가가 버그를 게시하면 실제로 해결해야 합니다. 아무도 유령 도시 포럼이나 해결되지 않은 버그의 거대한 목록을 보고 싶어하지 않습니다.
웹 API 요약
웹 서비스와 API는 풍부합니다. 불행히도 대다수는 사용하기 어렵습니다. 그 이유는 설계 불량, 문서 부족, 변동성, 해결되지 않은 버그 또는 경우에 따라 위의 모든 것까지 다양합니다.
이 게시물의 지침을 따르면 웹 API가 깨끗하고 문서화되어 있으며 사용하기 쉬운지 확인하는 데 도움이 됩니다. 이러한 API는 정말 드물기 때문에 널리 채택되고 사용될 가능성이 훨씬 더 높습니다.