Web API 设计和开发: 개발자를 위한 기본 指导方针

소프트웨어 애플리케이션은 여러 가지 면에서 우리의 삶을 더 쉽고 편리하게 만들어주었습니다. 우리는 거의 매일 애플리케이션을 사용하며, 어떤 사람들은 다른 사람과의 상호작용보다 애플리케이션을 더 자주 사용하기도 합니다.

그렇다면 애플리케이션은 어떻게 서로 상호작용할까요? 바로 API, 즉 애플리케이션 프로그래밍 인터페이스를 통해 이루어집니다. 이 글에서는 API가 무엇인지 알아보겠습니다. 특히 웹 API와 그 설계 및 개발에 초점을 맞출 것입니다.

웹 API란 무엇인가요?

웹 API는 웹에서 사용하도록 설계된 API의 한 유형입니다. 즉, 웹 기반 소프트웨어 애플리케이션, 시스템 및 서비스는 웹 API를 사용하여 인터넷을 통해 정보를 교환합니다. 일반적으로 JSON 또는 XML과 같은 형식으로 요청을 보내고 응답을 받습니다.

웹 API는 다음과 같은 이유로 최신 소프트웨어 개발에서 중요한 역할을 합니다:

상호 운용성: API는 기술에 구애받지 않으므로 기술 스택에 관계없이 서로 다른 소프트웨어 시스템이 서로 통신할 수 있습니다. 이를 통해 개발자는 다양한 애플리케이션을 원활하게 통합할 수 있습니다

.
확장성: 웹 API는 모듈식 개발을 지원하므로 애플리케이션의 다양한 구성 요소를 독립적으로 빌드, 디버깅 및 확장할 수 있습니다. 이는 시스템의 확장성을 크게 향상시킵니다.

.
유연성과 확장성: 표준적인 惯例과 명확하게 정의되어 있는 규칙을 遵循하면 Web API는 응용 프로그램의 기능을 확장시키는 것을 도울 수 있습니다. 또한 개발자가 동적인 응용 프로그램을 만들 수 있는 程度의 유연성을 갖추고 있습니다.

Web API 開発战术

Web API는 요구 사항에 따라 다양한 战术을 사용하여 開発할 수 있습니다. 다음은 일반적으로 따라지는 战术의 예입니다:

REST – representational State Transfer (REST) API는 HTTP 프로토콜을 사용하여 操作을 수행합니다. 이들은 상태를 유지하지 않는 것을 의미하며, 각 요청은 수신자가 처리하고 응답하기 위해 모든 필요한 정보를 포함해야 합니다.
SOAP – Simple Object Access Protocol은 XML을 사용하여 정 structured way에서 정보를 교환합니다.
GraphQL은 API 조회와 수정에 사용되는 것입니다.
gRPC는 HTTP/2를 사용하여 정보를 이전하는 원격 프로시저 호출 프레임워크입니다.

이 sectiion은 API设计与开発을 탐구하며, 我们的讨论의 中心에 있는 REST API를 重点으로 하겠습니다.

요구 사항과 목표를 이해하는 것

모든 소프트웨어 개발 과정에서, 시작하기 전에 요구 사항과 지정적인 사용 사례를 이해하는 것은 중요합니다. 이렇게 하면 프로젝트에 필요한 자원, 시간, 비용 등을 计画하고 예측할 수 있습니다.

RESTful API를 제작하는 것과 同样하게도 이에 적용됩니다. 응용 프로그램이 상태 없이 정보를 교환하는지, 涉及到하는 实体을 자원으로 표현할 수 있는지, 서비스가 다양한 데이터 포맷을 사용하여 작동할 수 있는지 결정해야 합니다.

리суrcse와 エンド 포인트를 정의하는 것

REST API는 자원에 pivots, 이들은 시스템内의 데이터나 오브젝트를 表현하는 实体입니다. 각 자원은 고유의 URI로 자원 식별자를 갖습니다. 이러한 자원은 클라이언트에서 수신하고 요청을 처리하는 URL로 エンド 포인트를 통해 アクセス하고 조작할 수 있습니다.

ベストプractice는 자원을 명사로 끝말잇기를 하는 것이 좋습니다. 자원에 대한 operaion을 나타내는 동사보다는, 자원을 表현하는 명사를 사용하는 것입니다.

https://api.example.com/products

이 端点은 자원(이 경우, products)에 대해 명사를 사용하는 기본 慣例을 따른다. plural form – products? 를 사용한 것을 주의 해볼 수 있다. 여러 개의 오브젝트에 대해 작업하는 경우 plurals를 사용하는 것이 좋다.

그러나, 다음 端点 https://api.example.com/add-product은 명령어를 사용하고 자원에 대한 행동을 describe하려고 한다. 이 접근法은 더 복잡한 操作에서 어려울 수 있다.

표준 端点 이름 convension의 다른 중요한 측면은 层次적 구조의 사용입니다. 자원 간의 관계를 명확하게 표현하는 데 도움이 되ます.

例如: https://api.example.com/categories/{categoryId}/products/{productId}.
여기에서는 category와 product 자원之间的层次구조를 유지하는 端点을 정의합니다.

HTTP 方針과 상태 코드를 사용하는 것

REST API에서는 HTTP를 클라이언트와 서버之间的 통신에 사용합니다. HTTP는 자원에 대한 操作을 수행하는 주요 방법을 갖추고 있습니다. 아래는 이러한 방법과 其目的의 목록입니다:

GET – 자원의 자세한 정보를 가져오는 것。이러한 정보는 서버가 응답 메시지 몸에 돌려 주ет
POST – 새로운 자원을 생성합니다. 생성할 자원의 detaills는 요청 메시지 몸체에 送信됩니다.
PUT – 자원을 생성하거나, 사용 가능하면 자원을 갱신합니다. 생성하거나 갱신할 자원의 detaills는 요청 메시지 몸체에 送信됩니다.
DELETE – 자원을 제거합니다.
PATCH – 자원을 일부로 갱신합니다. 자원에 대한 변경사항은 요청 메시지 몸체에 送信됩니다.

유용한 REST API를 개발하기 위한 建议적인 방법은 자원에 대한 CRUD(생성, 읽기, 갱신, 제거) 操作을 적절하게 HTTP 방법을 사용하는 것입니다. 또한 API가 응답 메시지 몸체에 적절한 HTTP 상태 코드를 반환하도록 确保하는 것이 중요합니다.

상태 코드는 요청의 결과를 반영합니다. 아래는 몇 가지 일반적인 HTTP 상태 코드를 사용할 수 있습니다:

200 OK
201 Created
204 No Content
400 Bad Request
401 인증되지 않음
403 금지
404 없음
500 내부 서버 오류
503 서비스 사용 불가
504 ゲート웨이 시간 초과

API 端点正在处理的请求的结果，请使用适当的HTTP状态码准确表示。您还可以实现自定义HTTP状态码以描述特定于应用程序的行为。

版本策略

随着时间的推移，您开发的API将不断发展并进行更改。这就是版本化策略变得重要的地方。您必须确保已经使用您的API的客户端不会受到您所做的更改的影响。

维护不同版本将使您的API向后兼容，并允许客户端根据他们的需求使用他们偏好的API版本。Postman网站上的这篇信息性博客摘录解释了何时为您的API版本化是理想的：

“API를 변경하는 것이 第三条消费者이 그 API를 사용하기 위해 第三条 Their codebase를 수정해야 하는 경우에는 任何时候你的 API를 버전 관리해야 합니다. 이러한 변경은 ‘breaking change’と呼ばれ며, API의 입력과 출력 데이터 구조, 성공과 오류 응답, 그리고 安全 메カ니즘에 대해 行われ得ます.”

API 버전 관리는 다양한 방법으로 行われ 수 있습니다. 以下는 그 중 몇 가지 방법입니다:

URI 버전 관리: URL 경로에 버전 번호를 포함합니다. 例如, https://api.example.com/v1/products.
쿼리 PARAMETER 버전 관리: URL에 쿼리 PARAMETER로 버전 번호를 지정합니다. 例如, https://api.example.com/products?version=1.
HTTP 헤더 버전 관리: 요청의 HTTP 헤더에 버전 번호를 포함합니다. 例如, X-API-Version: 1와 같은 사용자 정의 헤더를 사용하여 해당합니다.
コン텐츠 negoesiation: 요청의 Accept 헤더에 버전을 지정하는 것이 一般的です. 媒体 유형을 사용하여 예를 들어 Accept: application/vnd.example.v1+json를 사용합니다.
埋め込힌 버전 관리: 응답의 媒体 유형 내에 버전 번호를 삽입합니다. 예를 들어 application/vnd.example.product-v1+json를 사용합니다.

보안 고려사항

API 개발 시 중요한 的另一面은 보안입니다. 다음과 같은 주요 사항을 기억해야 합니다.:

HTTPS를 사용하여 클라이언트와 서버之间의 정보 exchange를 암호화합니다.
인증과 권한 부여를 实施하여 자신의 권한을 가진 유저만 자원에 대한 operatioins을 수행할 수 있도록 만듭니다. 일반적인 方法은 Basic 인증, Bearer 또는 Token 인증, JWT, OAuth 2.0이며, 역할 기반 접근 제어를 사용하여 자원 이용을 관리합니다.
입력 유효성 검사 및 살균을 구현하여 SQL 인젝션 및 크로스 사이트 스크립팅(XSS)과 같은 취약성 공격을 방지합니다.
속도 제한 및 스로틀링을 구현하여 특정 시간 내에 클라이언트가 서버에 보낼 수 있는 요청 수를 제어합니다. 이렇게 하면 서버의 과도한 부하를 방지할 수 있습니다.

문서화

API 개발에서 핵심이지만 종종 간과되는 측면 중 하나는 문서화입니다. 사용자가 API의 특징과 기능을 이해할 수 있도록 문서화하는 것이 중요합니다.

문서는 포괄적이고 이해하기 쉬우며 표준 관행을 따라야 합니다. 요청 및 응답 본문, 사용된 HTTP 상태 코드 등의 예시를 포함하세요. Open API 사양을 참조하여 RESTful API를 설명할 수 있습니다.

소팅, 필터링 및 페이지 매김 전략

API를 개발하면 너무 많은 레코드를 리턴하게 되면 パフォーマンス 문제가 발생할 수 있습니다. 大量의 데이터를 가져오고 그 다음에 정렬하거나 필터링하는 것은 inefficient하며

이러한 문제를 해결하기 위해서는 레코드의 정렬과 필터링을 가능하게 하는 것이 좋습니다. 또한 페이지를 구현하여 가져오는 레코드 수를 줄이고, 이를 簡単하게 이동하고 처리하기 위한 제한을 셋팅해야 합니다.

使用량 모니터링, 로깅, 및 상태 체크

API 요청과 응답을 로깅하여 디버깅을 도울 수 있으며, API 사용 현황을 모니터링하여 응용 프로그램의 전반적인 パフォーマン스와 행동을 이해할 수 있습니다. 정기적으로 상태 체크를 하면 문제가 있으면 필요한 조치를 취할 수 있습니다. 이러한 모든 과정은 API를 더 健全하고 신뢰할 만하게 만들 수 있습니다.

결론

API, 특히 Web API는 인터넷上에서 소프트웨어 응용 프로그램과 통신하는 데 필요한 중요한 요소입니다.

이 articl은 Web API가 무엇인지, 왜 중요하는지, REST API를 주요 Target로 하는 다양한 開発方法을 설명합니다. 또한 자원과 端点(endpoint)를 정의하는 것, 표준 HTTP method과 상태 코드를 사용하는 것, versioining strategi, security consideratio, documentatio, 등의 주요 주제에 대해서도 배웠습니다.

이 articl이 interesting로 보였다면, freeCodeCamp의 다른 articl을 자유롭게 확인하고 LinkedIn에서 私와 연결하실 수 있습니다.