백업 2 : API 디자인 - sealamen/fifa_tools GitHub Wiki
(웹) API : 인터넷 네트워크를 사용하여 애플리케이션 간에 소통하는 방법. HTTP 프로토콜 사용. 인터넷 연결만 되어있다면 API 로 접근 가능
- 소프트웨어를 재사용 가능한 블록으로 만들어 본인 또는 다른 사람이 손쉽게 사용할 수 있도록 만듦.
- API 는 기본적으로 소프트웨어를 통한 소통이므로, API 디자인을 통해 재사용이 가능하도록 간결하고 쉽게 만들어야함
① API 는 다른 개발자들도 사용하며, 개발자들은 API 가 유용하고 단순하기를 기대
② 사소한 세부사항에 구애받지 않고 API 를 사용하고 싶어하므로, 구현을 숨기는 것이 목표
③ 잘못된 API 디자인은 시간, 비용 증가/ 보안 이슈 야기 / 조직 평판에 악영향 을 끼칠 수 있음
④ 같은 조직에서 만들어낸 API 는 모두 유사한 모양과 느낌이 들도록 하여 모든 API 가 이해하기 쉽고 사용하기 쉽게 만들어져야함
느낀점 : API 개요에 대한 부분이므로 어려움 없이 읽었다. API 개발을 진행할 때, 일단 REST API 의 형태를 최대한 따르고자 신경썼었는데, 정작 그래야하는 이유에 대해 생각하지 않았었구나 싶다. 하여튼 1장을 통해서 API 가 어떤 목표를 갖고 만들어져야 하는 지에 대한 이해가 생겼다.
사용자를 위한 API 를 만들기 위한 방법은 프로바이더의 관점에서 최대한 벗어나, 컨슈머의 관점을 유지하는 것
API 목표 캔버스 - 컨슈머의 관점을 갖기 위해 스스로에게 질문해볼 수 있는 요소들을 정리한 표 (책에서 제안)
누가 : API 를 사용할 사용자들
무엇을 : API 를 통해 사용자가 할 수 있는 일
어떻게 : 무엇을 하기 위한 방법
입력 : 각 단계를 진행하기 위해 필요한 요소 > 입력을 분석하여 누락된 누가, 무엇을, 어떻게를 다시 고려
출력 : 각 단계를 통해 발생할 쓰임새 > 출력을 분석하여 누락된 누가, 무엇을, 어떻게를 다시 고려
목표 : 어떻게, 입력, 출력을 정리하여 최종적으로 필요한 내용을 정리
식별한 내용들이 정말 컨슈머의 관심사인지를 다시 확인
아래의 요소들은 프로바이더 관점이 묻어나게하는 요인들이므로 API 디자인 시, 해당 요소들을 다시 고려해보아야 함
-
프로바이더에게 영향을 주는 요소
데이터 : 조직에서 사용하는 데이터의 체계와 이름을 일반화 ex ) CUSA, CUSB --> 고객정보A, 고객정보B
코드 및 비지니스 로직 : 해당 동작을 위해 발생할 동작을 모두 표현할 필요는 없음. 내부적으로 시스템이 어떻게 동작하는 지를 숨기는 것이 API의 목표
소프트웨어 아키텍쳐 : 비지니스 로직과 마찬가지로 소프트웨어 아키텍쳐 역시 숨겨져야함. API 목표 캔버스에서 도출한 무엇을, 어떻게가 소프트웨어 아키텍쳐에서 만들어진 결과는 아닌지 확인
인적 조직 : 부서 별로 역할이 다른 경우, API 구성에 여러 팀이 참여해야될 수 있음. 마찬가지로 컨슈머에게는 불필요한 노출이므로, 사용자가 무엇을 해야하는지에만 집중
느낀점 : 전자레인지 및 쇼핑 사이트 예시를 통한 설명으로 이해가 되었지만, 비슷한걸 한 번 해봐야 개발 시 적용할 수 있겠다는 생각이 든다. 책에서 친절히 가이드라인도 잡아주는 점도 좋아서, 한 번 개인 프로젝트에서 써먹어봐야지 싶다. 시간 안되면 과거 만들었던 데이터셋 관리 API 에 적용해보기라도 해야겠다.
REST API
- 효율적이고 확장 가능하며 안정적인 분산 시스템(함께 작동하고 네트워크를 통해 커뮤니케이션하는 서로 다른 컴퓨터에 있는 소프트웨어 조각)을 구축하기 위한 아키텍처
API 목표를 REST API 로 변형하는 과정
1. API 목표를 REST 리소스로 변환
- API 목표 캔버스를 통해 추출한 "목표"를 통해 리소스와 리소스 사이의 관계 식별
2. API 목표들을 액션으로 변환
- 개별 리소스와 리소스에 속한 파라미터들, 입력과 출력과 목표에 부합하는 리턴을 통해 액션을 식별
3. HTTP 프로토콜로 표현
- 리소스 경로 디자인 : 가장 일반적으로 사용되는 포맷 /{콜렉션 아이템의 타입을 반영하는 복수형 이름}/{아이템의 id}
- 액션에 맞는 HTTP 메서드 선택 (POST/GET/PATCH(PUT)/DELETE)
API 데이터 디자인하기
- 각 리소스들에 대해 이름/ 타입/ 필수 여부 판단 필요
- 파라미터는 반드시 필요한 데이터만을 제공해야함
REST 디자인 시, 균형 유지하기
- 적합한 HTTP 메서드가 없는 경우 POST 를 기본값으로 사용
- 사용자 친화적 / API 규칙 준수의 두 가지 목표로 작성하되, 우선 순위는 상황 및 팀에 따라 조정
API 의 명세 포맷
- 프로그래밍 인터페이스를 단순하고 구조화된 방식으로 설명하고 공유하는 방법\
OAS(OpenApi Specification)
- 단순한 텍스트 파일에 구조화된 데이터를 표현하는 방법
- 버전 지정 및 수정 사항 추적 가능
- 인터페이스를 보다 효율적으로 설명할 수 있도록 도와줌
- YAML/JSON 으로 작성 가능
예시
openapi: "3.0.0"
info:
title: Shopping API
version: "1.0"
paths:
/products:
description: The Products catalog
get:
summary: Search for products
description: |
Search for products in catalog using a free query parameter
parameters:
- name: free-query
description: |
상품의 이름(name), 참조값(reference), 또는 상품 설명의 일부(partial description)
in: query
required: false
schema:
type: string
responses:
"200":
description: |
Products matching free query parameter
post:
summary: Add product
description : |
Add product (described in product info parameter) to catalog
responses:
"200":
description: |
product added to catalog- paths: API 의 리소스
- /products: 리소스의 경로
- summary : 액션에 대한 짧은 설명
- description: 리소스의 설명
- responses: API 의 응답결과. 반드시 하나는 있어야함
- parameters: 액션의 파라미터 목록
- name : 파라미터 이름
- in: 파라미터의 위치
- required : 파라미터의 필수 여부 (required/description)
- schema: 파라미터 데이터 구조
느낀 점: API 문서 작성하는 방법... 보면서 따라하면 될 듯싶긴 한데, 몹시 귀찮아보이므로 swagger 가 없었으면 이거 일일이 하고있었겠지 싶다. 좀 감사함을 느끼며 추후에 스웨거문서 한 번 손봐야겠다.