오픈 API

오픈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의 주요 특징

1. 명확한 API 문서화
   • API의 동작 방식, 요청 및 응답 형식을 명확하게 정의함.
   • Swagger UI와 같은 도구를 활용하여 시각적으로 확인 가능.
2. API 테스트 및 실행
   • OpenAPI 문서를 통해 API 요청을 테스트하고 응답을 확인할 수 있음.
3. 다양한 언어 지원
   • Java, Python, Node.js, Go 등 다양한 언어에서 OpenAPI 기반으로 API 개발 가능.
4. 자동화된 코드 생성
   • OpenAPI 명세를 기반으로 API 클라이언트 및 서버 코드 자동 생성.
   • 예: openapi-generator를 활용하여 Java Spring, Python Flask 등의 API 코드 생성 가능.
5. 버전 관리와 협업 용이
   • 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

https://www.data.go.kr

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)을 포함

1. 웹 서비스 보안(WS-security)
2. WS-ReliableMessaging
3. 웹 서비스 주소지정(WS-addressing)
4. 웹 서비스 기술 언어(WSDL)

REST(RESTful) 조건 6

1. 클라이언트-서버 아키텍처
2. 스테이트리스(stateless) 커뮤니케이션 (세션 정보는 클라이언트 저장)
3. 일부 데이터는 캐시 가능
4. 표준화된 형식의 인터페이스
5. 계층화된 시스템 제약 (계층적 조정 가능한)
6. 코드 온디맨드 (코드를 전송해 클라이언트 기능확장, 선택적)

REST(RESTful) 이란 – 쉬운 설명

1. REST(Representational State Transfer)
   • 넓은 의미: 자원을 식별하고 자원의 상태를 주고 받는 모든 것
   • 좁은의미: HTTP로 CRUD를 실행하는 API
2. 가벼운 요청-응답 구조, 이해와 사용이 쉬운 API
   • 자원에 대한 상태를 요청하고,
   • 다양한 표현(JSON, XML, HTML, XLT, TXT)로 응답
3. REST 아키텍처 원칙 세트
   • 프로토콜이나 표준이 아님
   • API 개발자는 REST를 다양한 방식으로 구현

HTTP 명령어

HTTP 명령어와 CRUD

• POST: 등록(Create)
• GET: 조회(Read)
• PUT: 수정(Update)
• DELETE: 삭제(Delete)