Open API

 

 

 

API(Application Programming Interface) 

 

흔히 말하는 IT 개발에 필요한 운영체제나 시스템, 애플리케이션, 라이브러리 등을 활용해 다양한 응용 프로그램을 작성하게 해 주는 인터페이스.

 

인터페이스는 일종의 약속이라고 생각함. 어떤 기능을 가지고 처리할 수 있게 하는 함수나 프로그램의 로직을 사용하기 위해 어떻게 호출하는지에 대한 호출 방법, 사용 시 필요한 매개변수, 얻게 되는 반환 값 등이 어떻게 작성되어 있으니 이렇게 사용하라는 약속인 것임.

 

Open API는 누구나 사용할 수 있도록 공개된 API. 즉 API 중 플랫폼의 기능이나 콘텐츠를 외부에서 웹 프로토콜로 호출해 사용할 수 있게 해 주는 개방형 API임. 기관이나 기업이 보유한 다양한 정보나 애플리케이션 등을 타 정보 시스템에서 사용할 수 있도록 공개하는 것으로 간단하고 직관적인 인터페이스 제공을 통해 데이터를 표준화 하고 프로그래밍하는 외부 개발자나 사용자 참여를 유도하는 사용자 중심의 비즈니스 모델임.

 

보통 Open API를 통해 어떤 서비스를 개발해 제공할 때에는 기존에 존재하는 기능을 확장할 수도 있고 처음부터 만들 수도 있음.

 

Open API는 원래 Swagger라는 프로젝트의 사양을 기반으로 함. Swagger는 개발자가 RESTful 웹 서비스를 설계, 빌드, 문서화, 소비할 때 필요한 모든 일들을 도와줄 수 있는 오픈 소스 소프트웨어 프레임워크임. 대부분의 개발자들은 Swagger UI 도구나 툴셋을 통해 자동화된 문서와 코드 생성, 테스트 케이스 생성 등을 지원함.

https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

 

 

 

apigee에서는 API를 어떻게 개발하고 유지하고 사용하는지에 대한 라이프사이클을 정의함. 먼저 API의 상태를 Build, Use, Run 상태로 구분하고 각각의 상태에 맞춰 세부 단계를 나누고 있는데 예를 들어 Build 단계에서는 모델, 개발, 문서, 테스트할 수 있는 작업을, Use 단계에서는 API 제공 및 모니터링, 비용 측정 등의 작업을 하게 됨. 이렇게 API를 개발하는 것은 단순히 함수 하나를 만드는 것만이 아니라 API를 누가 사용할 것인지와 제공하는 쪽에서는 어떠한 쪽으로 향후 발전을 가져갈지 고려하는 것이 좋음.

API 설계 및 디자인을 위해서는 다음과 같은 내용을 따르는 것이 좋음.

 

1) JSON 문서 포맷 사용 권장
2) 각각의 필요한 서비스에 대한 적절한 정의가 설계되어 있어야 함
3) 파라미터에 의해 응답 값 모델을 변경하지 않는 작업
4) Collection과 entity를 적절히 최적화하여 사용
5) 버저닝 관리
6) 기본 값과 데이터의 양이 많을 때는 페이징 처리




출처
본 포스트는 인프런 이도원 강사님의 "Spring Boot 3.x 를 이용한 RESTful Web Services 개발" 강의를 통해 직접 작성 및 정리한 글입니다.