우리는 웹서비스와 API(Application Programming Interface)를 어디서든 찾을수 있습니다, 그러나 대부분은 사용하기 고통스럽습니다. API를 사용하여 웹 서비스에 연결한 후 "저 사람들은 도대체 무슨생각을 하고 있는 걸까?" 라는 의문이 든 적이 있으 신가요? 저희도 그런 경험을 가지고 있으며 API로 서비스를 연결하는 것은 매우 혼란스러울 수 있습니다. 잘못된 디자인, 누락된 문서, 지속적인 변경, 버그 등으로 인해 API를 사용하는 것은 종종 어려움을 겪습니다.
하지만 꼭 그럴 필요는 없습니다. 우리는 매혹적인 웹 API를 만들 수 있으며, 그리고 즐겁게 만들 수 있습니다. 그렇다면 좋은 API를 만들기 위한 핵심은 무엇일까요?
준비하시고, 이해해봅시다 어떻게 사람들이 즐겨 찾는 API를 다지안할 수 있을지!!
The Importance of Good API Design
API들은 기업의 중요한 자산입니다. 고객들은 API를 캐주얼하게 사용하는것이 아니라 시간과 돈을 통합,코딩,학습에 투자합니다. 하지만 API에 지나치게 의존하는 데에는 어려움이 따릅니다. API 사용 중단에 따른 비용은 상당할 수 있으며, API가 운영에 중요한 역학을 하는지 보여줍니다.
잘 설계된 공개 API는 사용자를 유치하고 유지할 수 있는 큰 잠재력을 가지고 있습니다. 그러나 잘못된 API 설계는 기능 장애로 인한 지원 요청의 폭주와 같은 문제를 빠르게 야기할 수 있습니다. 이는 기업의 가장 큰 디지털 자산을 골칫거리로 만들 수 있습니다.
API의 이러한 이중적 특성은 API를 설계할 때 신중함과 정확성이 중요하다는 점을 시사합니다. 목표는 단점보다 더 많은 이점을 제공하는 API를 만드는 것입니다.
제품을 개발할 때는 보통 기술 전문 지식이 없는 일반 사용자를 염두에 두고 있습니다. 우리는 그들이 원하는 것이 무엇인지에 대한 의견을 수렴하여 친숙한 인터페이스를 만듭니다. 하지만 API 개발은 다릅니다. 숙련된 프로그래머를 위한 인터페이스를 만드는 것이기 때문입니다. 이들은 사소한 문제도 발견하고 우리만큼이나 비판적일 수 있습니다.
API 디자이너로서의 관점은 사용자의 관점과 약간 다릅니다. 우리는 API가 수행하거나 제공해야 하는 기능에 초점을 맞춥니다. 반면 사용자는 최소한의 노력으로 필요한 것을 쉽게 얻는 것을 중요하게 생각합니다. 이러한 서로 다른 관점이 문제를 야기합니다. 핵심은 우리의 관점을 사용자의 관점과 일치하도록 바꾸는 것입니다. 당연해 보이지만 이러한 사용자 중심 접근 방식을 취하는 API는 거의 없습니다.
Characteristics of a Good API
양질의 API에는 효과성, 유용성, 장기적인 성공에 기여하는 몇 가지 특징이 있습니다
| 특징 | 설명 |
| 배우기 쉽다. | 사용자는 API의 기능과 기능을 빠르게 파악할 수 있어야 합니다. |
| 문서없이도 사용하기 용이하다. | API는 문서에 광범위하게 의존하지 않고도 효과적으로 사용할 수 있어야 합니다. |
| 사용하기 쉽다. | 디자인은 올바른 사용법을 안내하고 오용을 방지해야 합니다. |
| 읽고 유지보수하기 용이한 코드이다. | API를 사용하여 작성된 코드는 명확하고 유지 관리가 가능해야 합니다. |
| 충분히 잘 강력하고 요구사항을 잘 만족시킨다. | API는 충분한 이용성으로 유저의 요구를 잘 만족시킵니다. |
| 손쉬운 확장 | 새로운 기능을 추가하는 것은 합리적이고 직관적이어야 합니다. |
| 사용자 친화적이다. | API의 디자인과 특색이 유저의 예상에 맞아 떨어져야 합니다. |
이제 좋은 API를 만드는 요소에 대해 살펴봤으니 이제 API를 설계하기 위한 팁으로 넘어가겠습니다.
Requirements Gathering
양질의 API를 설계하기 위한 첫 번째 중요한 단계는 사용자로부터 요구 사항을 수집하는 것입니다. 이 과정에 비판적인 태도로 접근하세요. 사용자는 종종 근본적인 요구사항에 초점을 맞추기보다는 특정 솔루션을 제안합니다.
우리의 임무는 사용자가 핵심 사용 사례를 통해 언뜻 보기에는 숨겨져 있는 근본적인 요구사항을 발견하도록 하는 것입니다. 처음 제안된 '솔루션' 아래에 더 나은 디자인 아이디어가 숨어 있을 수 있습니다.
또한 다양한 문제를 해결할 수 있는 매우 다재다능한 API를 구상하는 것은 흥미로운 일입니다. 하지만 먼저 사용자의 실제 요구사항에 집중해야 합니다.
높은 수준의 기능 사양 초안을 작성하여 설계 프로세스를 시작하세요. 이 초기 실험 단계에서는 포괄적인 세부 사항보다 속도와 유연성이 더 중요합니다.
초안을 대상 사용자 및 기타 이해관계자들과 널리 공유하세요. 피드백에 귀를 기울이면 더 나은 제품을 만드는 방법에 대한 귀중한 인사이트를 얻을 수 있을 것입니다.
핵심은 초기에 너무 많은 가정을 하지 않는 것입니다. 요구 사항 수집은 기초를 다지는 작업이므로 공식적인 API 설계로 넘어가기 전에 시간을 들여 제대로 파악하세요.
One API, One Purpose
우수한 API를 설계하기 위한 핵심 규칙은 너무 많은 다양한 문제를 해결하려고 하기보다는 한 가지 주요 문제를 잘 해결하는 데 집중해야 한다는 것입니다.
많은 사용 사례를 다루려는 일반적인 “Swiss army knife” API를 만들면 실패하는 경우가 많습니다. 특정 사용자 요구와 연결된 뚜렷한 목적이 없으면 범위가 너무 흩어지게 됩니다. 모든 사람의 모든 것이 되려고 하면 기능이 얕아집니다.
대신 구축하는 각 API의 범위를 제한하세요. 목적이 명확하고 집중적으로 유지되도록 하세요. 모든 기능을 뚜렷한 사용자 니즈 충족이라는 목표에 직접 연결하세요. 주변적인 것은 모두 제거해야 합니다.
예를 들어 주소 유효성 검사에만 초점을 맞춘 API는 목적이 분명합니다. 신용카드 거래에만 초점을 맞춘 API는 기능은 다르지만 여전히 협소한 기능을 정의합니다.
Clarity and Consistency
API의 전반적인 명확성과 일관성에 기여하는 몇 가지 효과적인 네이밍 관행과 표준화된 응답을 살펴보겠습니다.
Choosing intuitive names
좋은 API를 설계할 때 명확성은 엔드포인트와 리소스에 대해 선택하는 이름에서 시작됩니다. 명명 규칙을 일관되게 채택하고 적용하면 개발자는 마치 공통 언어를 사용하는 것처럼 API를 직관적으로 이해할 수 있습니다. 예를 들어, 사용자 정보를 검색하기 위해 "/users"와 같은 엔드포인트에 RESTful 규칙을 사용하는 것은 업계 표준에 부합합니다. 이를 통해 개발자는 과도한 문서화 없이도 엔드포인트의 목적을 파악할 수 있습니다.
| 명확한 네이밍을 해라 | |
| https://example.com/api/user => X | http://example.com/users => O |
트랜잭션 처리를 담당하는 API 엔드포인트가 있다고 가정해 보겠습니다. POST 엔드포인트의 경우 "/process"와 같은 일반적인 이름 대신 트랜잭션 처리를 나타내는 "/transactions"와 같은 이름을 사용하는 것이 더 RESTful할 수 있습니다. 이렇게 명시적으로 이름을 지정하면 혼동을 방지하고 엔드포인트의 기능을 명확하게 전달할 수 있습니다.
| 불명확성을 피해라 | |
| https://exmaple.com/api/process => X | https://example.com/api/transactions => O |
Consistent data formats
API를 설계할 때는 API가 데이처 요청에 어떻게 응답할지 고려하는 것이 중요합니다. 응답데이터를 일관되게 구조화 하면 API 소비자를 위한 통합이 쉬워지고 개발 주기가 빨라집니다.
주어진 사용자 ID에 대해 프로필 정보를 반환하는 사용자 프로필 API endpoint를 예로 들었을때 주요 사용자 속성을 일관된게 구조화하여 응답하는것이 세부정보를 안정적으로 파싱할 수 있게 됩니다. 모든 프로필 응답에 이름,이메일,나이,위치 항상 4가지의 예측가능한 JSON구조를 응답하는 것이 사용자 측면에서 직관적인 통합이 가능 합니다.
{
"name" : "Meot",
"age" : 19,
"address" : "seoul",
"email" : "meot@meot.com"
}
Documentation is Key
Describe endpoints and methods
API 문서에서 엔드포인트와 사용 가능한 메서드를 명확하게 정의해야 합니다. 이것은 사용자가 API에서 무엇을 할 수 있는지를 이해하는 데 필수적입니다. 엔드포인트는 API에서 접근 가능한 URL이며, 메서드는 해당 엔드포인트에 대해 수행할 수 있는 작업을 정의합니다. 각 엔드포인트와 메서드는 설명되어야 하며, 가능한 경우 예제를 제공하는 것이 좋습니다.
Provide examples and tutorials
실제 예제와 함께 튜토리얼을 제공하는 것은 사용자가 API를 더 잘 이해하고 활용할 수 있도록 돕는 중요한 요소입니다. 이를 통해 사용자는 실제 코드를 보면서 API의 작동 방식을 배울 수 있습니다. 예제는 각 엔드포인트 및 메서드의 사용법을 보여주는 데 도움이 됩니다.
Keep documentation up-to-date
API 문서는 항상 최신 상태여야 합니다. 새로운 엔드포인트, 메서드 또는 기능이 추가되거나 변경될 때마다 문서도 업데이트되어야 합니다. 이를 통해 사용자는 항상 최신 정보에 접근할 수 있습니다.
Sharing it with peer developers
API 문서는 개발자 커뮤니티와 공유되어야 합니다. 이를 통해 다른 개발자들이 API를 효과적으로 활용할 수 있으며, 협업 프로젝트에서도 유용합니다. 또한, 피드백을 받고 문서를 개선할 수 있습니다.
Achieving Stability Through Versioning
URL versioning
URL 버전 관리는 API 버전을 엔드포인트 URL에 포함시키는 방법입니다. 각 버전에 대해 별도의 엔드포인트를 유지하고 새 버전이 출시되면 새로운 URL을 제공합니다.
https://api.example.com/v1/resource
https://api.example.com/v2/resource이러한 방식은 사용자가 특정 버전에 명시적으로 액세스할 수 있어 편리합니다. 그러나 URL이 길어지고 복잡해질 수 있으며, 엔드포인트를 변경해야 할 경우에는 추가 작업이 필요합니다.
Parameter versioning
Parameter 버전 관리는 요청 매개변수나 쿼리 매개변수를 사용하여 API 버전을 지정하는 방법입니다.
https://api.example.com/resource?version=1
https://api.example.com/resource?version=2이 방법은 URL을 보다 간결하게 유지할 수 있으며, 엔드포인트가 변경되지 않습니다. 그러나 매 요청마다 버전을 지정해야 하므로 번거로울 수 있습니다.
Header versioning
Header 버전 관리는 HTTP 요청 헤더를 사용하여 API 버전을 전달하는 방법입니다. 헤더에는 일반적으로 Accept 또는 사용자 지정 헤더를 사용합니다.
Accept: application/json; version=1
Accept-Version: 2이 방법은 URL을 깔끔하게 유지하면서도 버전 관리를 효과적으로 처리할 수 있습니다. 그러나 클라이언트에서 헤더를 설정해야 하므로 구현이 복잡할 수 있습니다.
Key considerations for API versioning
- 이전 버전과의 호환성: 새로운 버전이 출시되면 이전 버전과의 호환성을 유지하는 것이 중요합니다. 사용자가 쉽게 마이그레이션할 수 있도록 설계되어야 합니다.
- 사용 중단 정책: 각 버전의 수명 주기를 명확히 전달하고, 사용 중단 예고와 마이그레이션 계획을 제공해야 합니다.
- 변경 로그: 각 버전에 대한 변경 로그를 제공하여 사용자가 새로운 기능 및 변경 사항을 이해하고 마이그레이션할 수 있도록 합니다.
Effective Error Handling
효과적인 오류 처리는 사용자 친화적인 API 설계의 핵심입니다. 오류가 발생했을 때 사용자가 쉽게 디버깅하고 문제를 해결할 수 있도록 돕는 것은 중요합니다. 이를 위해 몇 가지 핵심 요소를 고려해야 합니다.
Clear Error Codes and Messages
오류 코드와 메시지는 사용자가 쉽게 이해하고 식별할 수 있어야 합니다. 이들은 무엇이 잘못되었는지 명확하게 알려주어야 합니다. 예를 들어, "404 Not Found"나 "403 Forbidden"과 같은 HTTP 상태 코드를 사용하면 클라이언트가 어떤 문제가 발생했는지 즉시 파악할 수 있습니다.
Consistent error structure
API에서 발생하는 모든 오류는 일관된 구조를 갖도록 설계되어야 합니다. 이는 사용자가 오류를 처리하는 방법을 예측할 수 있도록 돕습니다. 예를 들어, 모든 오류 응답이 특정 형식의 JSON 객체를 반환하도록 하여 클라이언트가 오류를 쉽게 처리하고 해석할 수 있게 합니다.
Providing contextual information
오류 응답에는 발생한 오류에 대한 추가적인 컨텍스트 정보를 포함하는 것이 도움이 됩니다. 이 정보는 사용자가 문제를 해결하는 데 도움이 될 수 있습니다. 예를 들어, 오류가 발생한 위치나 해당 작업에 필요한 권한 등의 정보를 제공할 수 있습니다.
{
"error": {
"code": 404,
"message": "Requested resource not found",
"description": "The resource you are trying to access does not exist.",
"context": {
"resource": "/api/users/123",
"user_id": "123"
}
}
}
이러한 방법을 통해 API 사용자는 오류를 더 쉽게 이해하고 처리할 수 있으며, 개발자가 문제를 빠르게 해결할 수 있습니다. 그 결과로 사용자 경험이 향상되고, 개발자 간의 협업도 더욱 원활해집니다.
Security Measures
API 액세스 보안은 단순한 모범 사례를 뛰어넘습니다. 데이터를 보호하고 API에 대한 신뢰를 확보하는 것이 절대적으로 필요합니다. 효과적인 API 설계는 보안을 핵심 요소로 적절히 통합하여, 인증 및 권한 부여 프로세스를 간소화하고 동시에 무단 액세스 및 잠재적인 보안 위협으로부터 강력하게 방어합니다.
API keys
API 보안은 단순히 모범 사례를 따르는 것 이상입니다. 데이터 보호와 신뢰성 확보는 필수적입니다. 효과적인 API 설계는 보안을 중요 요소로 취급하여 인증 및 권한 부여를 간소화하고 동시에 무단 액세스와 보안 위협으로부터 강력하게 방어할 수 있는 기능을 제공해야 합니다.
Advanced authentication and authorization
세밀한 접근 제어가 필요한 경우 OAuth 2.0과 같은 고급 인증 메커니즘을 고려해야 합니다. 이를 통해 사용자 데이터에 대한 안전한 액세스를 제공할 수 있습니다. 예를 들어, OAuth를 사용하면 사용자가 명시적으로 승인한 작업만을 안전하게 제한할 수 있습니다.
Comprehensive rate limiting
속도 제한은 API의 남용과 디도스 공격으로부터 보호합니다. 스팸을 방지하고 서비스의 안정성을 유지하기 위해 API 사용량을 제한하는 것이 중요합니다.
Handling sensitive data
민감한 데이터는 안전한 전송 및 저장이 보장되어야 합니다. TLS와 같은 프로토콜을 사용하여 데이터 전송 중에 암호화를 적용하고, 사용자 자격 증명에 대한 안전한 저장 방식을 구현하여 보안을 강화할 수 있습니다.
Security headers and CORS
HTTP 보안 헤더를 활용하여 API와 소비자를 보호하는 추가적인 보안 계층을 추가할 수 있습니다. 또한 CORS 정책을 신중하게 구성하여 무단 도메인 간 요청을 방지하고 API에 접근할 수 있는 도메인을 제어할 수 있습니다.
이러한 보안 요소들을 통합하여 API를 설계하면 데이터 보호와 신뢰성을 보장하고 사용자의 개인 정보를 안전하게 보호할 수 있습니다.
좋은 API를 작성하는 영어 원문을 읽고 요약하고 서머리하며 하며 문서를 만들어 봤다. 좋은 API를 만들려면 사용자가 편하게 이해하고 사용할 수 있어야 한다. API를 사용하는 사람들은 종종 문서를 보지 않고도 바로 사용할 수 있는데, 그렇게 하려면 API의 이름과 구조가 명확해야 할것이고 그렇게 작성해야 겠다.
그리고 API를 만들 때에는 한 가지 목적에만 집중하는 것이 중요하다는 것도 알게 되었다. 복잡하고 다양한 기능을 하나의 API에 넣으면 오히려 혼란스러울 수 있다고 하니 한가지의 역할에만 충실해야 겠다.
API 문서도 반드시 제공되어야 하고, 예제와 튜토리얼이 함께 제공되면 사용자가 쉽게 이해하고 활용할 수 있겠지? 또한, API의 안정성을 유지하기 위해 버전 관리와 오류 처리, 그리고 보안이 중요하다는 것도 배웠다. 사용자에게 편리한 경험을 제공하기 위해서는 이런 것들을 고려해야 한다는 거다.
그래서 결론적으로, 좋은 API 디자인은 사용자가 편리하게 이용할 수 있는 서비스를 제공함으로써 더 나은 경험을 선사한다.
출처
How to Design a Good API?
We can find web services and APIs (Application Programming Interfaces) everywhere, but many are painful to use. Have you ever connected a web service using its API and wondered, "What were they thinking?" We have, and connecting services via API can be con
blog.bytebytego.com