그러나 저자는 프로젝트가 실제로 시작된 후 몇 가지 심각한 문제에 직면했습니다 .
1. 완전한 API 문서 및 사양이 부족합니다 .
· API 문서는 불완전하고 오류가 많아 정확한 참고 자료로 사용할 수 없습니다.
· 합의된 API 테스트 프로세스가 없으므로 백엔드 개발 팀이 통지 없이 API를 마음대로 변경하고 출시할 수 있습니다. 이러한 변경 사항은 종종 버그이며 API 클라이언트와의 통합을 중단합니다.
2. 부적절한 API 프레임워크 및 검증 :
백엔드 팀은 부적절한 Flask 프레임워크를 사용하고 복잡한 페이로드 검증을 자체적으로 구현했지만 대부분은 테스트되지 않았습니다.
· 검증 부분에는 날짜, 타임스탬프, 문자열 형식 검증 등 많은 양의 코드가 포함되어 있지만 아직 완전히 테스트되지 않아 프로젝트 진행 속도가 심각하게 느려지고 있습니다.
따라서 위의 문제를 해결하려면 정확성 과 완전성을 보장하기 위해 API 문서를 수정 하고 개선해야 합니다 . 사양을 충족하지 않습니다.
API 디자인 및 문서 수정
위에서 노출된 문제를 보면 개발팀이 REST API 및 OpenAPI 사양의 모범 사례를 이해하지 못하고 있음을 알 수 있습니다. 따라서 개발팀은 먼저 OpenAPI와 작동 방식을 이해하고 API 설명서를 OpenAPI 사양에 통합하여 API의 예상 동작을 보다 명확하게 이해해야 합니다.
OpenAPI 사양에 문서를 통합하는 과정에서 우리는 이전 API 디자인에서 많은 문제점을 발견했습니다. 예를 들어 이전에는 사용자 정의 날짜 형식을 사용하려면 서버 및 UI에서 사용자 정의 유효성 검사 논리가 필요했습니다. 날짜를 표시하기 위해 OpenAPI에서 지원하는 ISO 표준으로 전환하여 이 문제를 해결했습니다.
게다가 일부 모드는 너무 유연해서 검증이 거의 효과가 없습니다. 유효성 검사를 개선하기 위해 스키마를 리팩터링하고 각 엔터티에 대해 서로 다른 끝점이 있는 모델을 생성하여 더 유용하게 만들었습니다.
이전 디자인에서는 HTTP 메소드와 상태 코드가 부적절하게 사용되었습니다. 팀에서는 GET 및 POST 메서드만 사용하며 모든 응답은 200 상태 코드를 반환합니다. 이러한 부적절한 사용으로 인해 리소스를 생성, 삭제 또는 업데이트하려고 할 때 불분명해집니다. 이 문제를 해결하기 위해 우리는 HTTP 메소드의 사용을 재정의하고 요청의 성공 또는 실패를 보다 정확하게 나타내기 위해 적절한 상태 코드를 올바르게 반환했습니다.
이전 디자인의 또 다른 제한 사항은 "엔드포인트 재사용"이었습니다. 코드를 절약하는 것처럼 보이지만 실제로는 너무 많은 구현 세부 정보를 노출합니다. 따라서 먼저 API를 설계한 후 구현을 고려하는 개념을 강조해야 합니다.
API 사양을 OpenAPI와 병합하는 것은 프로젝트의 중요한 전환점이 되었습니다. 그런 다음 백엔드와 통합하기 전에 모의 서버를 실행하여 UI를 구축 및 테스트하고 사양에 따라 백엔드 구현을 확인할 수 있었습니다. 우리는 Prism을 사용하여 모의 서버를 실행하고 Dredd를 사용하여 서버 구현을 확인합니다(지금은 Schemathesis를 사용하는 것을 선호하지만). 이를 통해 프로젝트를 보다 명확하고 효율적으로 개발할 수 있습니다 .
API 게시 프로세스 수정
API 문서가 있더라도 출시 전 API 사양에 대한 테스트를 거치지 않으면 문서의 역할이 제한됩니다. 문서 자체는 API의 작동 방식을 이해하는 데 도움이 되지만 API의 진정한 힘은 서버가 올바르게 구현되었는지 확인하는 확인 도구로서의 기능에 있습니다.
API 서버가 예상대로 실행되는지 확인하기 위해 Dredd 테스트 제품군을 지속적 통합 서버에 통합했습니다. Dredd 검증을 통과하고 API 사양을 준수하지 않는 한 누구도 새 코드를 병합하고 게시할 수 없습니다. 이 단계를 통해 팀은 API 서버에 대한 실수로 수정되는 것을 방지할 수 있습니다. 이제부터 서버에 대한 모든 변경 사항은 사전에 문서화되어야 하며 API 서버는 병합 또는 게시 전에 이러한 변경 사항을 준수하는지 확인해야 합니다. 이 접근 방식은 서버의 안정성과 일관성을 보장합니다.
올바른 API 개발 프레임워크 선택
이전에 팀은 웹 애플리케이션 구축에 널리 사용되는 Python 프레임워크인 Flask 프레임워크를 사용하여 API 서버를 구현했습니다. 그들은 기본 Flask로 API를 구축하고 API 페이로드를 검증하기 위해 많은 사용자 정의 코드를 작성했습니다. 이는 경험이 부족한 많은 API 개발자가 저지르는 일반적인 실수입니다.
사용자 정의 API 유효성 검사 계층을 구축하는 것은 바람직하지 않지만 이 접근 방식에 지나치게 의존하면 바퀴를 재발명하게 될 수 있습니다. API에는 API 전체에서 구현되어야 하는 페이로드와 URL(경로 및 쿼리 매개변수)을 처리하기 위한 복잡한 유효성 검사 논리가 필요합니다. 따라서 자체 API 검증 레이어 구축을 고집한다면 결국 API 프레임워크를 생성하게 됩니다. 하지만 사용할 수 있는 우수한 API 개발 프레임워크가 많이 있으므로 그중 하나를 선택해 보는 것은 어떨까요?
특히 Flask의 경우 고려해야 할 몇 가지 옵션이 있습니다. 그러나 모든 프레임워크가 동일하게 생성되는 것은 아닙니다. 예를 들어 flasgger, Restx(flask-restplus의 후속 버전), Flasgger, Flask-RESTful 및 Flask-smorest 등이 있습니다. 선택의 여지가 너무 많은데 어떻게 결정을 내리나요?
REST API 개발 프레임워크를 선택할 때 다음 요소를 고려해야 합니다.
· OpenAPI 지원 : 프레임워크는 REST API를 쉽게 구축하고 API 문서를 자동으로 생성하여 페이로드 검증의 정확성을 보장해야 합니다. 참조 프레임워크에는 Flasgger 및 Flask-smorest가 포함됩니다.
· 강력한 데이터 검증 : 페이로드 검증에는 다양한 속성과 유형을 처리할 수 있는 강력한 데이터 검증 라이브러리가 필요합니다. 라이브러리는 문자열 형식(ISO 날짜 및 UUID)과 같은 선택 및 필수 속성은 물론 엄격하고 완화된 유형 유효성 검사를 지원해야 합니다. Python 생태계에서 pydantic과 marshmallow는 뛰어난 데이터 검증 라이브러리이며 Flasgger와 Flask-smorest는 마시멜로를 사용할 수 있습니다.
· 포괄적인 검증 : 프레임워크는 요청 페이로드, 응답 페이로드, URL 경로 매개변수 및 URL 쿼리 매개변수의 검증을 지원해야 합니다. 일부 라이브러리는 요청 페이로드만 검증하고 URL 매개변수 또는 응답 페이로드를 무시할 수 있습니다. 프레임워크가 유효성 검사 규칙을 시행하는 방법을 하나 이상 제공하는지 확인하세요. 마시멜로를 사용하는 경우 해당 모델을 사용하여 응답 페이로드를 직접 확인할 수 있습니다.
· 성숙도 : 성숙하고 안정적이며 활발한 커뮤니티 지원을 받는 도서관을 선택하세요. 좋은 문서화와 사용자 문제를 신속하게 해결할 수 있는 능력이 있어야 합니다.
위의 요소들을 평가한 후, REST API에 대한 데이터 검증을 쉽게 구축하기 위해 마시멜로 사용을 지원하는 Flask 플러그인인 Flask-smorest를 선택했습니다. 데이터 검증 프로세스를 단순화하고 사용자 정의 코드의 양을 줄일 수 있습니다. 이제 요청 및 응답 페이로드 모두 올바르게 검증되었으며 마시멜로에서는 URL 쿼리 및 경로 매개변수의 검증도 처리합니다.
올바른 API 프레임워크를 선택하면 API가 작동할 수 있습니다. 프레임워크가 API 계층의 세부 사항을 처리하기 때문에 우리는 애플리케이션의 비즈니스 로직과 데이터 모델에 더 집중할 수 있어 개발 속도가 향상되고 더 나은 소프트웨어를 더 자주 출시할 수 있습니다.
훌륭한 API를 구축하려면 모든 것을 고려하세요 .
오늘날의 인터넷에서는 API가 어디에나 있고 피할 수 없습니다. 그러나 실제로 좋은 API를 구축하는 것은 읽기 쉽고 유지 관리하기 쉬운 코드를 작성하는 것과 마찬가지로 고품질의 사용하기 쉽고 수정하기 쉬운 인터페이스를 구축하는 것도 API 개발에서 어려운 일입니다.
고품질 API를 제공하는 것은 비즈니스 요구 사항과 일치해야 하기 때문에 어렵습니다. 즉, 클라이언트와 서버는 동일한 규칙과 사양을 사용해야 합니다. 그렇지 않으면 통합을 달성하기가 어렵습니다.
이 목표를 달성하려면 고객 요구 사항 수집, 요구 사항을 기술 세부 사항으로 변환, API 설계, 문서 작성, 적절한 API 프레임워크 선택 및 올바르게 사용, API 테스트, 구현이 설계 사양을 충족하는지 확인 등 여러 측면을 고려해야 합니다. 여기에는 API 보안, 배포 및 운영과 같은 측면은 포함되지 않습니다.
비즈니스에 중요한 API를 구축할 때 주니어 개발자에게만 맡겨두지 않는 것이 좋습니다. 참여할 수 있지만 작업을 안내하려면 선임 개발자가 필요합니다. API 개발 경험이 없다면 모범 사례 경로를 따르십시오. 먼저 API를 설계한 다음 문서를 작성하고 사양에 따라 구현하고 확인하십시오. 바퀴를 재발명하지 말고 올바른 프레임워크를 선택하세요!
OpenAPI를 배우고, API 테스트 프레임워크를 이해하고, API 개발 프레임워크를 연구하는 등 시간이 좀 걸릴 수 있지만 그만한 가치가 있습니다. 그렇지 않으면 API 통합 및 소프트웨어 품질 문제의 악순환에 빠지게 되어 프로젝트 진행을 방해하고 문제 해결에 막대한 비용이 발생하게 됩니다.
충분한 리소스와 숙련된 API 개발자가 있다면 API를 올바르게 구축할 확률이 크게 높아지고 많은 비용을 절약할 수 있습니다. 또한, API 관리에도 주의를 기울여야 합니다. 초기 개발 및 지출 비용뿐만 아니라 개발 과정에서 숨겨진 코드 문제와 담당 직원의 불명확한 인계로 인해 숨겨진 위험이 발생할 수 있는 문제도 많습니다. 따라서 Power Simple Integration은 API 관리가 타사 도구를 사용하여 원스톱으로 API를 관리하고, 여러 역할을 참여시키고, 책임 회피를 피하고, 개발 효율성을 향상시킬 수 있다고 믿습니다.