오픈API 란?
OpenAPI는 RESTful API의 명세(specification)를 정의하는 표준입니다. 이를 통해 API의 구조, 요청 및 응답 형식, 인증 방식 등을 일관되게 문서화하고, 개발자들이 쉽게 API를 이해하고 사용할 수 있도록 돕습니다. (일반적으로 회원가입과 사용승인을 거쳐 사용)
1. OpenAPI의 개요
- 표준화된 문서 형식
OpenAPI는 API의 엔드포인트, 요청 및 응답 데이터 형식, 인증 방식 등을 YAML 또는 JSON 형식으로 문서화할 수 있도록 제공합니다. - 자동 문서 생성 지원
OpenAPI 문서를 기반으로 Swagger UI 같은 도구를 사용하면, 자동으로 API 문서를 생성하고 테스트할 수 있습니다. - 코드 자동 생성
OpenAPI 명세를 기반으로 클라이언트 및 서버 코드를 자동으로 생성할 수 있어, API 개발 속도를 높이고 오류를 줄일 수 있습니다.
오픈API 용어 정리
- API: 응용 프로그램 작성을 위한 인터페이스
- 대표적 방법 2가지: SOAP, REST
- 공개 여부에 따라: Open, Close (proprietary)
- 오픈API: 원하는 사람들이 사용할 수 있도록 규격을 공개 한 API
- API키 또는 인증키: 인증된 사용자임을 입증하는 고유한 문자열
- JSON: (JavaScript Object Notation, 가볍고 사용이 편리해서 많이 사용)JavaScript 객체 문법으로 구조화된 데이터를 표현하기위한 표준 포맷
- XML: (eXtensible Markup Language) 구조화된 데이터를 표현하기위한 확장 가능한 다목적 마크업 언어
2. OpenAPI의 주요 특징
- 명확한 API 문서화
- API의 동작 방식, 요청 및 응답 형식을 명확하게 정의함.
- Swagger UI와 같은 도구를 활용하여 시각적으로 확인 가능.
- API 테스트 및 실행
- OpenAPI 문서를 통해 API 요청을 테스트하고 응답을 확인할 수 있음.
- 다양한 언어 지원
- Java, Python, Node.js, Go 등 다양한 언어에서 OpenAPI 기반으로 API 개발 가능.
- 자동화된 코드 생성
- OpenAPI 명세를 기반으로 API 클라이언트 및 서버 코드 자동 생성.
- 예:
openapi-generator를 활용하여 Java Spring, Python Flask 등의 API 코드 생성 가능.
- 버전 관리와 협업 용이
- API 변경 사항을 체계적으로 관리하고, 협업 시 혼선을 방지할 수 있음.
3. OpenAPI와 Swagger의 차이
| 구분 | OpenAPI | Swagger |
|---|---|---|
| 정의 | API 명세를 위한 표준 | OpenAPI를 구현한 도구 |
| 사용 목적 | REST API 정의 및 문서화 | API 문서화, UI 제공, 테스트 가능 |
| 파일 형식 | YAML, JSON | YAML, JSON (Swagger UI 사용) |
Swagger는 OpenAPI를 기반으로 동작하는 도구이며, OpenAPI는 표준 자체를 의미합니다.
결론
OpenAPI는 REST API의 명세를 정의하는 표준으로, 문서화, 테스트, 코드 자동 생성 등의 기능을 제공하여 API 개발 및 협업을 용이하게 합니다. Swagger 같은 도구를 활용하면 OpenAPI 문서를 시각적으로 확인하고, API 요청을 테스트할 수도 있습니다.
추가 정보
공공데이터 포털과 오픈API
공공데이터 포털(data.go.kr): 매우 다양한 데이터와 오픈 API 와 제공
https://www.data.go.kr/tcs/dss/selectDataSetList.do?keyword=도로명+주소
SOAP vs REST
- SOAP (Simple Object Access Protocol)
- REST(Representational State Transfer)
SOAP (Simple Object Access Protocol)과 REST (Representational State Transfer) API는 웹 서비스를 구현하는 두 가지 주요 방식입니다. 주요 차이점을 아래 표로 정리하겠습니다.
| 비교 항목 | SOAP | REST |
|---|---|---|
| 프로토콜 | 독자적인 프로토콜 (XML 기반) | HTTP 프로토콜을 활용 |
| 데이터 형식 | XML만 지원 | JSON, XML, YAML 등 다양한 형식 지원 |
| 전송 방식 | HTTP, SMTP, TCP 등 다양한 프로토콜 지원 | HTTP 기반 (GET, POST, PUT, DELETE 활용) |
| 보안 | WS-Security, SSL/TLS, 인증 및 권한 부여를 명확하게 지원 | 주로 SSL/TLS, OAuth 2.0 등을 사용 (보안 구현이 상대적으로 단순) |
| 성능 및 속도 | XML 기반의 무거운 메시지 구조로 인해 상대적으로 느림 | JSON을 주로 사용하여 가볍고 빠름 |
| 트랜잭션 지원 | ACID(원자성, 일관성, 격리성, 지속성) 지원 가능 | 기본적으로 지원하지 않음 (애플리케이션에서 처리 필요) |
| 서비스 계약 | WSDL(Web Services Description Language)을 사용하여 서비스 계약 정의 | 일반적으로 OpenAPI (Swagger) 또는 기타 문서화 도구 활용 |
| 유연성 | 엄격한 표준을 따르며 구조화됨 | 설계가 유연하고 확장성이 높음 |
| 사용 사례 | 금융, 엔터프라이즈 시스템, 보안이 중요한 환경 | 웹 서비스, 모바일 애플리케이션, 클라우드 API |
어떤 것을 선택해야 할까?
- SOAP: 보안이 중요한 금융 시스템, 엔터프라이즈급 애플리케이션, 강력한 트랜잭션 관리가 필요한 경우 적합.
- REST: 빠른 응답 속도와 확장성이 필요한 모바일 및 웹 애플리케이션, 클라우드 서비스 등에 적합.
즉, SOAP은 보안과 신뢰성이 중요한 경우, REST는 경량화된 서비스와 확장성이 중요한 경우 사용하면 좋습니다.
SOAP (Simple Object Access Protocol)
다른 언어, 다른 플랫폼의 애플리케이션이 통신할 수 있도록 설계된 최초의 표준 프로토콜. 높은 복잡성과 오버헤드가 있지만 보안과 트랜잭션(ACID)을 포함
- 웹 서비스 보안(WS-security)
- WS-ReliableMessaging
- 웹 서비스 주소지정(WS-addressing)
- 웹 서비스 기술 언어(WSDL)
REST(RESTful) 조건 6
- 클라이언트-서버 아키텍처
- 스테이트리스(stateless) 커뮤니케이션 (세션 정보는 클라이언트 저장)
- 일부 데이터는 캐시 가능
- 표준화된 형식의 인터페이스
- 계층화된 시스템 제약 (계층적 조정 가능한)
- 코드 온디맨드 (코드를 전송해 클라이언트 기능확장, 선택적)
REST(RESTful) 이란 – 쉬운 설명
- REST(Representational State Transfer)
- 넓은 의미: 자원을 식별하고 자원의 상태를 주고 받는 모든 것
- 좁은의미: HTTP로 CRUD를 실행하는 API
- 가벼운 요청-응답 구조, 이해와 사용이 쉬운 API
- 자원에 대한 상태를 요청하고,
- 다양한 표현(JSON, XML, HTML, XLT, TXT)로 응답
- REST 아키텍처 원칙 세트
- 프로토콜이나 표준이 아님
- API 개발자는 REST를 다양한 방식으로 구현
HTTP 명령어
HTTP 명령어와 CRUD
- POST: 등록(Create)
- GET: 조회(Read)
- PUT: 수정(Update)
- DELETE: 삭제(Delete)